This tutorial is for programming beginners to show how easy it can be to get an interactive site up and running.
Yesterday, I launched a new site that I’ve been thinking about creating for a while.
I keep retweeting job adverts from friends of mine and thought it would be great if I could keep them in one place for other people to browse without having to see the rest of my tweets. Not everyone is into cat videos as much as I am. Unfortunately.
I bought the domain techjobsin.london on Wednesday morning and started coding in the afternoon. It was a quick site to build — around two hours from starting to getting it online — which surprised a few people. Was the quick speed of completing the site because I’ve been doing coding for years? Yes and no.
Programming languages power all the internet yet they’re not understood by 99.9% of internet users. It’s hard to understand what is possible — and how long it takes — if you don’t understand the tools used to create the internet.
I’ve taught a few hundred people how to code and one trait I see again and again is that students suddenly realise what is possible and how long it takes once they have a little bit of knowledge.
But how do we know which one of the hundreds of programming languages to choose? PHP? Python? Node? It’s down to picking a good tool for the job of creating the web. Ruby on Rails is my particular favourite way to code web sites. It’s a beautiful, friendly and quick way to make dynamic websites.
This Ruby on Rails tutorial is for people who’ve never programmed before. I’ve tried to go as slow as possible. If you can install applications on your computer, you should be able to complete this tutorial.
Developers have tendencies to get pedantic (read: pissy) about some of the ways taught below. The following is done for the sake of human clarity rather than computer clarity.
Installing Ruby on Rails
If you’re on a Mac and have Mavericks (10.9) or Yosemite (10.10), you’re fine for now. If you’re on a Windows computer or a Mac with 10.6, 10.7 or 10.8, the easiest way to install Rails is to use RailsInstaller.
RailsInstaller will install Ruby 1.9.3, Rails 3.2 plus a ton of other little, useful tools. However, we want to be using the very latest version of Rails which as of October 2014 is Rails 4.1.
Rails 4.1 introduces lots of nice things that we can use when we’re building bigger sites. We won’t be using most of the new features but as we’re starting a brand new site, we might as well use the very latest version of the software. We’ll talk about how to upgrade to the latest version of Rails in a minute.
The command line
As with any programming, we’re making custom software that’s never been created before so we have to use tools that help us create custom software.
The first tool we use heavily in coding is the command line. This is a tool that lets you get under the hood of your operating system.
You’ve probably seen a command line in movies. When the nerdy one tries to break into the bank’s mainframe, they’ll be using a black screen with green text. That’s a command line. Imagine hacking bank’s mainframe using Excel or iTunes — it would be impossible. You need powerful tools to do powerful work. This is why we use the command line.
There are tools built into your operating system that let you play around with the command line. On Windows, it’s called Command Prompt which can be found under the Start menu, and on a Mac, it’s called Terminal which can be found in your Applications folder in the subfolder Utilities. Open it and you now have the same power as a movie’s hacker.
Most “commands” — the things we type into the command line — are pretty boring most of the time. Commands like change folder, make me a new file, list the files in a folder. It’s not always folder-related but 80% of the time, it will be basic.
If you’re on a Mac, it’s quite easy to try out the command line. Open Terminal, type into your command line the following and press enter:
say "I am a hacker"
You should hear the operating system saying those words. “Say” is a command and we’re telling it to say a particular phrase.
In coding, we call phrases like this strings. We’re sending a string to the command “say” to make the computer do something — in this case talk to us.
Updating the latest version
We’ll be using the command line quite heavily from here so open it ready to go.
You may or may not already have Rails installed. To see if you do, you can type in and press enter:
If you do, it will say something like “Rails 3.2.15" or “Rails 4.1.6". If not, you will get an error.
If you don’t see an error, to update to the latest version of Rails, type in and press enter.
gem update rails
If you do see an error, you will need to install Rails. Type the following and press enter.
gem install rails
You should see things happening. If you get a permissions error, you may need to add the word “sudo” to the start of either command and it will ask for your computer’s password.
sudo gem install rails
You should have the latest version of Rails set up on your computer now.
Where to put our project
The next step is we need to decide where to put our project. By default, the command line will drop us into what’s called the “home directory”. This is where your user account on the computer is.
Personally, I like to make a folder to keep all my projects in. I usually use the folder name “Sites”, but it’s up to you. Let’s create a folder to store any project that we make.
What is this ugly “mkdir”? We can break it down into two parts — “mk” and “dir”. First part is “make” and the second is “directory” (another way to say folder). So we’re telling the computer to make a directory called Sites.
Typing that command and pressing enter is the hacker way to create folders. We could have just found a place to right-click in Finder and pressed “New Folder” but this way makes you feel more like you’re in a movie, right?
We only ever need to do this once. Once we have the folder, it’s there until we delete it. We don’t need to do this again when we make a new project.
Next, we’ve made a folder but we’re not inside that folder. We’re still in our “home directory”. Let’s go inside the folder by “changing directory” (or cd for short).
You’ll see the bit next to the flashing cursor change to say something like Sites near the end. That means that we’re now inside the Sites folder. Once we’re in here, we can create our first project.
Creating our project
There are only two hard things in Computer Science: cache invalidation and naming things.
If I had a dollar for every second I’ve spent thinking what names to give to projects, I’d be able to afford some decent domain names.
I was lucky to get the domain techjobsin.london, it was still available, so it was obvious what I should call the project. I’ve called that project on my computer the very exciting name of “techjobs”.
You can call your Rails project whatever you like, just as long as it doesn’t have any spaces in the name and it’s all lower case, e.g. no to “Jobs Board” but yes to “jobsboard”. Your users won’t see this at all, you can brand your site however you like, this is just for your reference. Let’s stick with jobsboard for now. To create your project, type in the following and press enter.
rails new jobsboard
A lot of things will happen now. Rails will create all the files and folders you need for your project, plus download some gems. Gems are plug-ins for making your life easier and we’ll talk about them later. This process may take a minute or two depending on your internet connection.
One last command before we start. We need to go into the project itself, otherwise we’ll just say in our parent projects folder.
One more thing before we start coding
Rails has just generated a lot of files and folders for us. This is the skeleton for our jobs board but we need something to write our code in.
Code editors sound scary but just think of them like Microsoft Word. Instead of writing an essay for a human, you’re writing an essay for a computer to understand. The biggest the story, the more you need to write.
Open it once installed and you may get something that looks like this.
You may get a welcome screen or you may get a blank screen. For now, we just want to work on our jobs board project. Go to File > Open and find your project.
If you can’t find your project, you can go back to the command line and type in:
This will open the folder in your Finder/Explorer. You can also drag the folder to your dock icon which will open the folder. Once you’ve opened your project it should look something like the following.
We’re now ready to do some coding. Or are we?
Proper Planning and Preparation Prevents Piss Poor Performance
The most important part of doing any project is the planning. Let’s stop and think for a minute what we want to do on this site.
There will be a home page which will be a list of jobs, and there will be an area to add jobs (let’s leave it open to the public at the moment — we could add in admin only as a later feature).
There’s some more questions we need to answer here though. What if there’s 300 jobs… should there be pagination? What information should we take for people submitting jobs?
The best way to plan anything out is to sketch, sketch and more sketch. Invest in some good paper and pens (the hipster in me prefers Moleskine notebooks and Paper Mate Flair pens).
Here’s a sketch of how would do the project. Again, two pages needed, not that detailed, but I can see what I need before I start designing or coding the web site.
Once, I’ve sketched every page out, I know what I need for my project. I can see that I will need some pagination due to the left and right arrows at the bottom of my home page.
I could code the pagination myself but pagination is a fairly common thing on web sites. There may be another Rails developer in the world who has written some pagination code that’s better than I could write.
In Rails, you can download little snippets of code that you can use in your project — these are called gems. There are large and small gems for lots of different purposes. From making forms easier to whole CMS platforms.
I’ve previously written a Medium article on the best gems covers a lot of the common functionality that you get on websites. We’re going to use two gems in our project. Kaminari (a pagination gem) and Simple Form (a gem to make coding our new job form easier).
To add the gems to our project, we need to go to our code editor and edit the file called Gemfile.
Open the file, go right to the bottom and add in the following:
Remember to save your changes!
Your gems are ready to be installed. To download them to your project, go back to your command line and type in:
If we want to add any other gems to our project later, just edit your Gemfile again and run the bundle install command.
Models, views and controllers
Okay, we’re now going to stop for a minute to talk about Rails terminology. We’re going to separate our site into three different parts; models, views and controllers.
The first is called the views. For our project, this means the HTML for the site. For instance, we know that we’ll have some paragraphs so we code them in <p> tags. We might want to link somewhere, so we have <a> tags. If you don’t know much about HTML, Jon Duckett’s HTML and CSS Book is truly amazing. Buy it.
The second is called the models. Think of models as if they were sheets in an Excel (or Numbers) spreadsheet.
In my spreadsheet, I have a jobs sheet, a users sheet and a bookmarks sheet — I have three different types of data modelled in my spreadsheet.
In my jobs model, I have four columns; a job number, a title, a company and a URL, and there’s three job entries in my sheet.
The third part is called the controllers. This is Rails’s way for everything to talk together. For example, when we’re on the homepage, we want to get all the jobs from our spreadsheet and put into our index.html file in a particular way. When we’re on our add-a-job page, we want to make a new row in our spreadsheet and we want to show the user a form to complete.
What counts as a feature? On our site, it would be the ability to add and show jobs to the site. Another later feature could be the ability to submit your CV to a particular job. Another could be register as a user, or bookmarking jobs.
There’s a process I use whenever I add a new feature:
- Generate any models needed for the feature
- Update the database
- Generate any controllers needed
- Add in your URLs
- Fill in your models
- Fill in your controllers and views
- Finish feature, think of new feature and start from step 1 again
First thing in my feature process list is generate any models needed. Earlier we saw that in our spreadsheet for jobs we had four columns in there; job number, title, company and URL. We can ignore the job number as Rails handles this for us.
Rails has a few conventions — one of them is that the models are always title case and singular. For us, we’re going to call our model “Job”. Other models we could have include “User”, “Bookmark”, “Comment” or “Company”, but not “jobs”, “users”, etc.
Our first model is a Job model and it has three columns (ignoring the job number column) which are title, company and URL. We’re going to store them all as phrases or as we call them in computing, strings.
We can store data in lots of different formats such as numbers, true or false (called “booleans”), and dates. For what we need, we’re keeping with strings.
In our command line, lets type in:
rails generate model Job title:string company:string url:string
Lets break this down. We are generating a Rails model called Job with three columns which are strings. Make sure you get all the spaces correct.
This will create a few files that we need for our site which we’ll cover in the next step and in step 5.
Step 2 — your database is not your site
Unfortunately, when you make a model, it doesn’t automatically go into your database.
The database is the place you store data. This doesn’t live within Ruby or Rails but in a storage unit. We’ll use the default storage which is called SQLite3 and part of Rails by default, but we could use other ones such as MySQL or PostgreSQL. Don’t worry about this too much as Rails handles 95% of data handling for you. The only bit is doesn’t handle is updates to our database such as adding a new model or updating a model.
So let’s update our database with our brand spanking new Job model. In our command line, type in:
Watch out for spaces and colons here.
You should see something like “CreateJobs: migrated” towards the end when you press enter.
Now you might have noticed that this starts with “rake” not “rails”. There’s a technical reason for this but to keep it simple, rake is a way to run particular ruby commands on your command line. This is updating (or migrating) our database to the very latest version that it needs to be.
Step 3 — add your controller and views
Even though we have just one job model, we have two different pages on the site. We have a home page (or index page) and an add page (or new page).
Rails wants to be able to control which jobs you’re getting on which page. Our home page will behave differently to the new job page. This is where our controller comes in.
For this section of the site, we have a jobs area. On bigger sites, we will have multiple areas of the site with multiple controllers. For instance, we might want a résumé submission area of the site in the future — this would come under a different controller, one that deals solely with résumés. Other controllers could include a payments controller (if we decide to charge people) and a comments controller (if we decide to let people add comments to jobs).
We only need one controller at this point — solely dealing with the listing and addition of jobs. Just like with models, Rails makes controllers conform to conventions. Controllers are lower case and plural — so for this it would be “jobs”, “users”, “bookmarks” or “photos”.
We also want to make two pages to go along with this controller, the home page (in Rails, we call this the index page) and the add page (in Rails, we call this the new page).
Lets go back to our command line and type in:
rails generate controller jobs index new
Breaking that down, Rails is generating a controller called jobs and we’re also creating index and new pages with that controller.
Awesome. That’s all we need to generate for now.
Step 4— Adding in some URLs
URLs — or web addresses — are the biggest part of the web. We know that if we type in twitter.com into Chrome’s address bar, we’ll go to Twitter’s home page. If we go to twitter.com/riklomas, we’ll still go to Twitter but a particular page on Twitter — my profile page. The difference between the two links, and all links in fact, are key to how the web works.
For our site, we want to add in some URLs for going to different page. We have two particular pages that we want to go to. The home page and the add a job page.
To add these URLs we need to go back to our code editor. We need to find the file inside the config folder called routes.rb
This is where we can add our URLs. Keep the first line in tact and on the second line add the following.
You can even delete all the lines with “#” and with “get” in front of them. Keeping it super simple.
Save your file! There’s been a million times when I’ve forgotten to save files and code hasn’t worked properly.
We have some URLs we can go but our project’s code isn’t running. Lets go back to the command line and run our code. Type in:
You should get something like this:
Don’t worry about the content just yet. We’ll start filling that out in step 6.
Step 5 — Feeding our models
We want to make sure the data that comes through from our form. At the moment we could leave everything completely blank in the form in our sketches and that would be A-OK.
We want to make sure that the job definitely has a title, a company and a URL, otherwise the site would be full of blank jobs.
In our code editor, lets go to our model folder. You can find this within the app folder.
Notice in here we have a file called job.rb. This is the model that we generated earlier, let’s open this file and change:
class Job < ActiveRecord::Base
class Job < ActiveRecord::Base
validates :title, presence: true
validates :company, presence: true
validates :url, presence: true, uniqueness: true
What we’re doing here is making sure that our job’s title has some presence. In other words, making sure it isn’t blank. Same thing with our job’s company row. For our job’s URL, we’re making sure that it isn’t blank and it is unique as we don’t want any duplicate job posts.
These are called Rails validations and there’s a great list of them here.
Save the file and let’s go on to step 6 — the biggest step.
Step 6 — filling out our site
At the moment, there aren’t any jobs on our site. Our spreadsheet is empty. So let’s start with our new job page first. Go to http://0.0.0.0:3000/jobs/new or http://localhost:3000/jobs/new and you should see the HTML page on the left.
First of all, we need to create a new line in our database. To do this lets go to our jobs controller. Back to our code editor, go to the app folder, then the controllers folder and open jobs_controller.rb.
We want to change the new page, so the code that we’ll add will be in between lines 5 and 6 — the “def new” and the “end”.
“def” is just short for define — so when we define the new page, we want to say something about it. We want to create a new row in our job model.
@job = Job.new
Job.new means “hey, Job model, can we make a new one of you?”. But what about the first bit “@job”? This means send the new job we’ve created to our HTML so we can use it.
Think of the controller like a boxing match referee. In the red corner, we have the models and in the blue corner, we have the views. The controller is making sure both play by the rules that we decide.
Next thing to do is edit our HTML on our add a job page. Let’s go to the app folder, then views folder, then jobs folder and find new.html.erb.
We want to put a form in place of the dummy text. Replace all the text in this file with:
<%= simple_form_for @job do |form| %>
<%= form.input :title, label: "Job title" %>
<%= form.input :company, label: "Your company" %>
<%= form.input :url, label: "Link to job" %>
<%= form.button :submit %>
<% end %>
Remember that Simple Form gem we added earlier? This is where it comes in handy! Rails’s default form tags are a pain in the arse and Simple Form lives up to its name by making it a ton easier.
What this is doing is making a form for the new job we made in our controller with the columns in a particular order that we want. Save the file and refresh the page and you’ll get something like:
Try the form out. Fill it in with some details and submit the form. We should get an error. We’ve filled in the form but we can’t do anything with that form data yet.
So what’s happened? We’ve submitted the form but the form has nowhere to go.
Again, Rails has conventions. Whenever we have a new page, we submit the form and it goes to a create page. The create page is where the form data gets checked against the validations and if it passes, saves into the database. If it doesn’t pass, we want to show the form again with errors.
We actually have three pages on our site: index (home page), new (form page) and create (actually add the data from the form page).
Let’s go back to our jobs controller and add this create page to it. I’ve added in the following to our controller:
Next, we want to make a new job. Let’s change the create page to do that.
@job = Job.new
Phew, that’s a big change. So we’re creating a new job from our model, then if it saves, go to the home page (Rails likes to call this the “root path”), if it doesn’t save, render (or plainly, show the user) the HTML view called new.
If we try this now, it still won’t work because we haven’t put in our form data. We want to make sure that this data we send from the form is nice and secure. Remember the movie hackers from earlier? They really exist and we want to make sure that they can’t do bad things to our site such as making themselves administrators or stealing credit card details.
Let’s change one line in our create method to add this form data in. Change line 10 from:
@job = Job.new
@job = Job.new(params.require(:job).permit(:title, :company, :url))
Phew, that’s another big one. What we’re saying here is make a new job from the form data but only allow jobs to be submitted with title, company and url data. Our controller should look like this:
Now when we add in a new job, it should go back to the home page. That’s great but the last problem is that we can’t see any jobs on the home page!
The home page
Remember that Rails calls our home page the index page. Think of an index as being a list and in this case, our home page is a list of jobs. In our controller we want to get all our jobs in our database to show our users.
Let’s change our index page in our jobs controller from:
@jobs = Job.all
Here we have the home page getting all the jobs from the Job model and sending it to the HTML view as @jobs (we could name @jobs anything we want by the way, @all_jobs for example).
Our jobs controller is now finished:
Last thing we need to do is add those jobs to our home page’s HTML. Let’s go to our view for the jobs index page. This is in the app folder, in the views folder, in the jobs folder then open index.html.erb
We added a job earlier but there will be multiple jobs in here so we want to loop over each job and do some HTML with it. Let’s change all the text in index.html.erb to:
<h1>Jobs</h1><% @jobs.each do |job| %>
<h2><%= link_to job.title, job.url %></h2>
<p><%= job.company %></p>
<% end %><p><%= link_to "Add a job", new_job_path %></p>
Firstly, we have a title at the top called “Jobs” — that’s not anything special, you can change “Jobs” to “London jobs”.
The mid part is a loop. It takes each individual jobs from the controller and adds some particular HTML for each one. If there are 5 jobs, there will be 5 <div> tags with the class “job”, each with a <h2> tag and a <p> tag inside.
The last part has a tag called link_to. This is part of Rails and will make a link that goes to the new job page. There’s some magic underneath it all but it saves you from having to write <a> tags yourself.
If you save and refresh your homepage, you should see something like:
Click “add a job” and fill in the form again.
You can do this as many times as you like. The more jobs you add, the more there will be on the home page!
Our site looks so 1995 right now. 90s fashion seems to be having a comeback but for now, let’s give it a little bit of 2010s style.
For styling, we need to edit our stylesheets. For this, we’re going to go our app folder, then our assets folder, then stylesheets folder and open jobs.css.scss.
Replace all text with:
font: 14px/1.5 Helvetica, Arial, sans-serif;
margin: 20px auto;
It’s not a lot of CSS and you can go crazy on how your design looks. I’m keeping it nice and simple for now.
Remember back to the gems section? We said that we want pagination involved. We currently don’t have any pagination if we go over a particular number. All the jobs we ever post will be on the home page.
So how do we add in pagination? Remember we added in the Kaminari gem which does a lot of the hard work for us.
When adding a gem’s functionality, it’s always worth following the instructions, so for Kaminari, we need to add it into two places.
Firstly, back to our posts controller, we need to change:
@jobs = Job.all
@jobs = Job.page(params[:page]).per(25)
This means for every 25 jobs, paginate using the parameters sent through from the browser — I won’t go into this but look at the URL once it works.
The last part is to add some links on our home page to go back and forth. Go back to index.html.erb in app/views/jobs and add near the bottom (but not in the loop):
<p><%= paginate @jobs %></p>
This means that there will be pagination for the @jobs in our controller near the bottom of our home page in a paragraph tag. That’s it!
Stuck with any part of Rails? The best places to look are Google and Stack Overflow. If you get an error, copy and paste it into Google and see if anyone else has had the same problem before. If not, search on Stack Overflow and if nothing good, sign up and post a new question.
Commons errors are:
- Missing or too many “end”’s in your model or controller
- Check the difference between <%= and <% . I didn’t go into this but it’s always worth re-checking
- Spaces and non-spaces between things like colons
- Typos — they happen a lot, watch out for @jbos instead of @jobs for instance
- Not saving files — it’s a common mistake that professionals make
The average web developer salary in London is around £40,000 and developers are highly sought-after. I’ve been in the position of hiring developers and being a freelance developer, and what I’ve learnt is that a lot of development work just isn’t that hard.
A lot of developers hate me saying that because it “devalues their craft” but it’s a lot easier than it looks.
For the jobs board that we’ve made, I’ve edited 7 files and added 55 lines of code. Several of those lines were blank too. And of course I can make it more fully featured but it shows how quick it is to build sites like a jobs board.
Other things you could build using exactly the same tutorial:
- A blog (replace job with post)
- A link board like Delicious (replace job with link)
- A real estate listing site (replace job with house)
- A review site (replace job with album/movie/gig)
- A news site like Hacker News or Designer New (replace job with story)
techjobsin.london took about two hours to make and most of the time wasn’t coding, it was fiddling around with the design and stylesheets to make it look better.
Hopefully you can see that coding is a fun, creative outlet for lots of people that’s nowhere near as hard as it look at first glance.
- The official Rails guides are great: http://guides.rubyonrails.org/index.html
- RailsCasts are amazing, they’ve not been updated in a while as Ryan the owner is AWOL (come back soon Ryan) but they’re still very useful: http://railscasts.com/
- The Rails 4 Way book is meant to be very good: http://www.amazon.com/Rails-Way-Addison-Wesley-Professional-Ruby/dp/0321944275/
- Recommendation by Gaz Aston – The Ruby on Rails Guide eBook: http://www.amazon.co.uk/Ruby-Rails-Guide-Stefan-Wintermeyer-ebook/dp/B00E25KVLW
- For beginner Ruby, check out Why’s (Poignant) Guide to Ruby. Again, the author “Why” is AWOL (come back soon Why) but the book is a hilarious and fascinating way to learn Ruby. http://mislav.uniqpath.com/poignant-guide/book/
- For the best gems and services worth checking out, try my previous article. https://medium.com/@riklomas/my-favourite-ruby-gems-services-89fb47341c05