A hands-on intro to building modern web applications with Elixir and Phoenix
41 |
42 |
43 |
44 |
45 |
46 |
47 |
This is an important moment...
48 |
49 | I imagine right now you're feeling a bit like Alice. Tumbling down the rabbit hole. I can see it in your eyes. You have the look of a man who accepts what he sees, because he is expecting to wake up.
50 |
51 |
52 |
53 |
54 | Let me tell you why you're here. You're here because you know something. What you know you can't explain, but you feel it. You've felt it your entire life: that there's something wrong in the world. You don't know what it is, but it's there. Like a splinter in your mind, driving you mad. It is this feeling that brought you to me.
55 |
56 |
57 | Do you want to know what it is?
58 |
59 |
60 |
61 |
62 |
63 | After this, there is no turning back.
64 |
65 |
If you take the blue pill
66 |
The story ends, you navigate away from this page and you believe whatever you want to believe.
67 |
68 |
69 |
70 |
71 | You will keep believing that killing unicorns is a reasonable approach to keep processes from running away eating memory.
72 |
73 |
74 | You will keep believing that sidekiq solves your concurrency issues, even though you can't be sure that when your background tasks actually execute.
75 |
76 |
77 | You will keep believing your application is fault tolerant enough, even though you've spent zero thought about how your application should deal with exceptional cases.
78 |
79 |
80 |
81 | You will keep believing all functional programming languages have obnoxious syntax and that's the reason they have small followings and small communities.
82 |
83 |
84 |
85 |
86 |
If you take the red pill
87 |
88 | You stay in wonderland, and I'll show you how deep the rabbit hole goes.
89 |
90 |
91 | Remember, all I'm offering is the truth.
92 |
124 | In this tutorial you're going to build a simple CRUD app using Elixir and the Phoenix Framework. It will support new, create, index, edit,update,destroy and a homepage.
125 |
126 |
127 |
128 | When served in a production environment, pages can be rendered in microseconds, rather than milliseconds.
129 |
130 |
131 |
132 |
133 | This tutorial assumes you have experience building web applications using other languages and frameworks.
134 |
135 |
136 |
137 |
138 |
139 | Sometimes I will make analogies to Ruby on Rails, for clarity, so if you are not familiar with it, things might get a little confusing.
140 |
149 | If you follow through to the end of the tutorial, you will have built a web application with Phoenix and Elixir. The application will show a user generated quote that is randomly selected and pulled from a Postgres database. The quote will tell you why you should learn Elixir and should look like this:
157 | As you've noticed the Phoenix Framework is a web framework that is enjoyable to code in, and the Elixir language has Erlang's awesome performance and the BEAM virtual machine, all with syntax quite similar to ruby's.
158 |
159 |
160 |
161 | Elixir is a new language, but I expect it to take off in the future.
162 |
163 |
164 |
165 |
166 |
167 |
168 |
169 |
170 |
171 |
Want to brag about building an application in Phoenix?
122 | The first step to build a web application with the Phoenix Web Framework is to install the tools you need to start coding.
123 |
124 |
125 |
126 |
Installing Elixir
127 |
128 |
129 | Follow the Install Instructions from the Elixir-Lang homepage. This will install the Elixir and Erlang programming languages on your machine.
130 |
131 |
132 |
133 | The homebrew instructions worked seamlessly for me. Once you have installed Elixir, you can verify that it is properly installed by running the following commands:
134 |
161 | To get out of iex, press CTRL+C twice in a row.
162 |
163 |
164 |
165 | In the future, if you need to manage multiple versions of Elixir on the same machine, the exenv project, will do just that. For this tutorial though, we'll stick to using just the single version of Elixir that we just installed on your computer.
166 |
167 |
168 |
169 | The syntax of Elixir is very similar to ruby. The key differences are: macros instead of meta-programming, no classes or instance variables and pattern matching support.
170 |
171 |
172 |
173 | To get a feel for pattern matching in Elixir, read Pattern Matching in Elixir for Rubyists from DockYard, it covers the topic in an excellent manner.
174 |
175 |
176 |
177 |
Setting Up A Text Editor
178 |
179 |
180 | Most text editors don't include syntax highlighting for Elixir source code by default. There are packages for Sublime, but I will show you how to add support for Elixir into Atom. If you haven't installed the atom text editor, you can get it here.
181 |
182 |
183 |
184 | Once you load atom, select Atom>Preferences... in the menu. Select the "packages" button, filter for the language-elixir. Now you can install it. This will automatically highlight files with the extension ex and exs as elixir source code.
185 |
186 |
187 |
Installing and Setting Up Postgres
188 |
189 |
190 | Right now, Postgres is the only database supported by Ecto, which is what we'll be using to connect to our database. This makes deciding which to use easy!
191 |
192 |
193 |
194 | If you don't have Postgres installed yet, follow the instructions to install it.
195 |
196 |
197 |
198 | Then create an ecto user in Postgres:
199 |
200 |
201 |
$ createuser ecto --pwprompt
202 |
203 |
204 | Enter a password that you will remember.
205 |
206 |
207 | Then create the database for this project:
208 |
209 |
210 |
$ createdb -Oecto -Eutf8 splurty_development
211 |
212 |
213 | Make sure you can login to your postgres database by running the following command:
214 |
215 |
216 |
$ psql splurty_development --user ecto --password
217 |
218 |
219 | When it asks you for a password, enter it in the prompt. Once you get pulled into the postgres database prompt, press CTRL+D to exit.
220 |
221 |
222 |
Getting the Phoenix Framework
223 |
Navigate in the terminal to the directory where your different projects live and clone the phoenix source code:
224 |
229 | Navigate into the phoenix framework folder:
230 |
231 |
232 |
cd phoenix
233 |
234 |
235 | This tutorial is geared to work with Phoenix version 0.8. As it's changing quite quickly, you'll want to make sure you're using that version.
236 |
237 |
238 |
$ git checkout v0.8.0
239 |
240 |
241 |
242 |
Starting your first project
243 |
244 |
245 | You need to be in the same directory as the phoenix project. You need to get the dependencies and compile the phoenix project before you go any further.
246 |
247 |
$ mix do deps.get, compile
248 |
249 | Once that completes, run the following command:
250 |
251 |
252 |
$ mix phoenix.new splurty ../splurty
253 |
254 |
255 | This command will generate a new phoenix web project called splurty in the splurty directory of the parent folder.
256 |
257 |
258 |
259 | This is the first time we're using the mix command. Mix is a program that is a hybrid of bundler and rake if you're familiar with ruby on rails. In short it allows us to run commands and manages our dependencies.
260 |
261 |
262 |
263 | If you've tried programming in scala, or any other functional programming language, you may have noticed that package management is usually overly complicated. Mix is very well designed and works as simply as rake and bundler.
264 |
265 |
266 |
Running our Application: the Rise of the Phoenix
267 |
268 |
269 | Navigate to the directory that your splurty application is located in:
270 |
271 |
272 |
$ cd ../splurty
273 |
274 |
275 | Fetch, install and compile your application's source code and dependencies by running this command:
276 |
277 |
278 |
$ mix do deps.get, compile
279 |
280 |
281 | It should complete without showing you any error messages. Once it does you can start your server by running the following command:
282 |
283 |
$ mix phoenix.server
284 |
285 |
286 | Navigate your browser to localhost:4000 and see your generated phoenix web application. Awesome!
287 |
288 |
289 |
290 | Your application should look
291 | just like this at this step.
292 |
125 | Phoenix is a Model/View/Controller Web Framework and it has many parallels to Ruby on Rails. New projects have the root page displayed from the page controller's index action, but in this lesson we will override that. We will point it to a new controller, the quote controller and the homepage action.
126 |
127 |
128 |
129 | Pro-tip!
130 | One subtle difference you'll notice from rails is that in Phoenix, controller names tend to be in the singular rather than plural.
131 |
138 | In this lesson we'll setup a new controller, called the quote controller and setup an action called homepage.
139 |
140 |
141 |
Quick Overview
142 |
143 |
144 | Quickly look at the file structure that was generated when we created a blank Phoenix web application. The bulk of the interesting code is in the folder called web, it's like the app folder in Rails. You'll see channels, controllers, models, templates, views.
145 |
146 |
147 |
148 | Pro-tip! If you're coming from rails, views is serving a role close to what helpers do, and templates are the templates for HTML, that are generally put in Ruby on Rails views.
149 |
150 |
151 |
Create a Controller
152 |
153 |
154 | Build a new file in the folder web/controllers called quote_controller.ex, and have it be a blank controller. You can compare this to the page controller, as it's code is quite similar.
155 |
168 | Our goal now is to hook-up request to the root url of our application to go to the QuoteController and the homepage action (we'll hook the homepage action up in the controller a bit later).
169 |
170 |
171 |
172 | Run the following command to see which URLs are hooked up to which controllers and actions.
173 |
174 |
175 |
$ mix phoenix.routes
176 |
177 |
178 | Right now it will say:
179 |
180 |
181 |
page_path GET / Splurty.PageController.index/2
182 |
183 |
184 |
185 | Next, we want to change our routes so the root page goes to the QuoteController.
186 |
187 |
188 |
189 | To do this, edit web/router.ex to look like this:
190 |
defhomepage(conn,_params)do
255 | renderconn,"homepage.html"
256 | end
257 | end
258 |
259 |
260 | Save the file.
261 |
262 |
263 |
Building the View
264 |
265 |
266 | We'll need to build the view file to support our QuoteController.
267 |
268 |
269 |
270 | Build a new file in the web/views directory called quote_view.ex and put the following content in it:
271 |
272 |
273 |
defmoduleSplurty.QuoteViewdo
274 | useSplurty.View
275 | end
276 |
277 |
278 | Save the file.
279 |
280 |
281 |
282 | We are very close to having the root of our web application changed.
283 |
284 |
285 |
Build the template
286 |
287 |
288 | Create a new folder for quote templates in the application by running the following command:
289 |
290 |
291 |
$ mkdir web/templates/quote
292 |
293 |
294 | Then add a file to the web/templates/quote directory called homepage.html.eex with the following content:
295 |
296 |
297 |
298 |
Number of reasons I yolo everyday <%=10+14%>
299 |
300 |
301 | Save the file.
302 |
303 |
304 |
305 | Return to your web browser. Refresh the page at localhost:4000 and the page should update.
306 |
307 |
308 |
309 | You'll notice html.eex is similar to html.erb files in ruby. This allows you to template out HTML, and will execute elixir code, and display it to the page between the <%= and %>.
310 |
311 |
312 |
313 |
314 |
315 | Your application should look
316 | just like this at this step.
317 |
203 |
204 | The first thing this does is convert the id we extract from the parameters in the URL from a string to an integer. If we don't do this, Ecto will give us error messages about type errors.
205 |
206 |
207 |
208 |
209 | This also renders the show.html template and assigns the quote we load up from the Repo with the proper id into the @quote assignment.
210 |
211 |
212 |
213 | Refresh the page and you will see a different error message, which indicates we haven't build the template yet.
214 |
215 |
216 |
217 |
218 | Add the template file web/templates/quote/show.html.eex with the following dummy content within it:
219 |
220 |
221 |
hi
222 |
223 |
224 | Save the file and refresh the page. Excellent, the error goes away and are presented with the "hi" message.
225 |
226 |
227 | Add the saying and the author as headers on web/templates/quote/show.html.eex like this:
228 |
126 | In this lesson we will build a page to list out all the quotes in our application. We will use the QuoteController and index action.
127 |
128 |
129 |
130 | In advance we know we will build full CRUD functionality on the QuoteController, so we can setup the full set of RESTful, resourceful, routes all at once.
131 |
132 |
133 |
134 | To do this, edit web/router.ex and add the following line:
135 |
155 | end
156 |
157 | # Other scopes may use custom stacks.
158 | # scope "/api", Splurty do
159 | # pipe_through :api
160 | # end
161 | end
162 |
163 |
164 |
165 | Save the file.
166 |
167 |
168 |
169 | Whenever I change the routes file, I like to verify that my code changes did what I expected, so I will run the command to display the routes table:
170 |
171 |
172 |
$ mix phoenix.routes
173 |
174 |
175 | Right now it will say:
176 |
177 |
quote_path GET / Splurty.QuoteController.homepage/2
178 | quote_path GET /quotes Splurty.QuoteController.index/2
179 | quote_path GET /quotes/:id/edit Splurty.QuoteController.edit/2
180 | quote_path GET /quotes/new Splurty.QuoteController.new/2
181 | quote_path GET /quotes/:id Splurty.QuoteController.show/2
182 | quote_path POST /quotes Splurty.QuoteController.create/2
183 | quote_path PATCH /quotes/:id Splurty.QuoteController.update/2
184 | PUT /quotes/:id Splurty.QuoteController.update/2
185 | quote_path DELETE /quotes/:id Splurty.QuoteController.destroy/2
186 |
187 |
188 |
189 | The single-line code change hooked up the full set of RESTful routes on our QuoteController.
190 |
191 |
192 |
193 | Restart your server.
194 |
195 |
196 |
197 | Navigate in your web browser to the URL that looks like: localhost:4000/quotes. You should see an error message explaining there is an undefined function: Splurty.QuoteController.index/2.
198 |
199 |
200 | This indicates we must add an index action to the QuoteController. Edit web/controllers/quote_controller.ex and add it:
201 |
defindex(conn,_params)do
214 | renderconn,"index.html"
215 | end
216 | end
217 |
218 |
219 | Save the file and refresh the page. It will show you an error message that indicates the template index.html hasn't been created. This means we must create one.
220 |
221 |
222 |
223 | Create a file web/templates/quote/index.html.eex that contains the following text:
224 |
225 |
226 |
YOLO!
227 |
228 |
229 | Save the file and refresh the page. Awesome, we no longer see an error message, instead we see the text from our template file.
230 |
231 |
232 |
233 | We want this page to list out each of the quotes in our database, but right now our database has no quotes in it. Let's jump into iex and add a couple quotes in our database so this page has data it can display. To start with spin up iex by running the following command:
234 |
235 |
236 |
$ iex -S mix
237 |
238 |
239 |
240 | Store two quotes into the database, by running commands like this:
241 |
242 |
243 |
> quote = %Splurty.Quote{saying: "They hate us, cause they ain't us.", author: "Dave Skylark"}
244 | > Repo.insert(quote)
245 |
254 | Since we now have two quotes in our database our goal will be to list all of the quotes in our database on the index template.
255 |
256 |
257 |
258 | The first step is to load the quotes in our controller, and allow our template access the records.
259 | Edit the index action in web/controller/quote_controller.ex so the code looks like this:
260 |
281 | This will render the index.html.eex template and give the template access to @quotes, which will be a list of all the quotes that exist in our database.
282 |
283 |
284 |
285 | Edit web/templates/quote/index.html.eex and replace it's contents with this, so it displays a table on the page, with a table row for each record in our database:
286 |
122 | We want our splurty application to splurt out un-expected quotes to the user from the database.
123 |
124 | This means the homepage action of the QuoteController should load up a quote randomly from the database, and then show the details for the quote. We will do that in this lesson.
125 |
126 |
127 |
128 | Before we keep coding, since you're staying up to date with cutting edge technologies, like Elixir and Phoenix we thought you may be interested in giving back and helping teach the next generation of web developers....
129 |
130 |
131 |
132 |
133 | Take an Aspiring Web Developer Under Your Wing
134 |
135 |
136 | Here's the gist:
137 |
138 |
139 | Me and a few other developers are running theFirehoseProject - a 12 week mentor driven online coding program to train the next generation of web developers.
140 |
141 |
142 | Our code mentors take a student under their wing for 12 weeks, pair program with them for one-hour per week and guide them towards their personal coding goal.
143 |
144 |
145 | Throughout each week, students work on building several web applications (think Yelp and Udemy clones), solve real-world coding challenges (from FizzBuzz to LinkedLists), build a web app through TDD and join a group project to build a chess game as a team.
146 |
147 |
148 | Our mentors are senior web devs from PayPal, Techstars companies, ex-Flickr, ex-bit.ly and get excited by seeing a beginner grow into a proficient developer who's able to solve complex CS challenges.
149 |
150 |
151 | You can see what some of our students are saying about us here and find more info about what our mentors are doing here.
152 |
153 |
154 |
155 | If you're interested email marco@thefirehoseproject and we'll give you more details!
156 |
157 |
158 |
159 |
160 |
161 | Ok, the plug is over, let's get back to coding.
162 |
163 | Ecto's query syntax is quite nice for simple queries. See an example here.
164 |
165 | Unfortunately it doesn't allow us to perform an ORDER BY RANDOM() from SQL easily.
166 |
167 | This means we'll need to craft a custom SQL query and load up a Splurty.Quote based on that.
168 |
169 |
170 |
171 | We will build a submodule within quote.ex that will allow us to put various queries inside it. In this module we can build a random method that will execute a SQL query to extract a random record and parse the result into a Splurty.Quote model. To do that, add the following lines of code to web/models/quote.ex:
172 |
defmoduleQueriesdo
183 | defrandomdo
184 | query=Ecto.Adapters.Postgres.query(
185 | Repo,
186 | "SELECT id, saying, author from quotes ORDER BY RANDOM() LIMIT 1",
187 | [])
188 | %Postgrex.Result{rows:[row]}=query
189 | {id,saying,author}=row
190 | %Splurty.Quote{id:id,saying:saying,author:author}
191 | end
192 | end
193 | end
194 |
195 |
196 |
197 |
198 | Save the file.
199 |
200 |
201 | Now we can extract a random quote from our database by calling Splurty.Quote.Queries.random.
202 |
203 |
204 |
205 | Modify the homepage action within the QuoteController to hook this functionality up. The homepage action should load a random quote, assign it to @quote and render the show.html template. To do that edit web/controllers/quote_controller.ex to look like this:
206 |
121 | In order to allow the application to accept user generated quotes, we will need to build form where the user is prompted to enter details about the quote they want to add. We also will need to store the quote in the database when the form button is pressed. We will accomplish both in this lesson.
122 |
123 |
124 |
Building a new form
125 |
126 |
127 | Right now if you navigate to localhost:4000/quotes/new, you'll see an error message indicating we need to add the new action to the controller.
128 |
129 |
130 |
131 | Edit web/controllers/quote_controller.ex and add the new action to it:
132 |
defnew(conn,_params)do
150 | renderconn,"new.html"
151 | end
152 | end
153 |
154 |
155 | Save the file.
156 |
157 |
158 |
159 | Refresh the page. The error message will change, and it will say that the new.html template doesn't exist. This means we will need to create a file called new.html.eex. To start with create the web/templates/quote/new.html.eex file with the following content:
160 |
161 |
162 |
Hello!
163 |
164 |
165 |
166 | Save the file and refresh the page. We no longer are presented with an error message, instead we see the text: Hello!
167 |
168 |
169 |
170 | In this lesson we'll want to use routing helpers to build URLs in our controller. To do that, we'll want to include the routing helpers by adding the following lines of code to web/controllers/quote_controller.ex:
171 |
221 | Save the file and refresh the page. Awesome, the form appeared!
222 |
223 |
224 |
Dealing with CSRF
225 |
226 |
227 | Next, we should plan to support the creation of a quote in the database. Navigate to localhost:4000/quotes/new, populate the form with data and press the submit button.
228 |
229 |
230 |
231 | An error message is displayed, indicating problems with CSRF. This is because we're not passing along a valid CSRF token in the form we're submitting.
232 |
233 |
234 |
235 | Add the following helper method to web/view.ex, to allow us to get the CSRF token from the template:
236 |
237 |
238 |
defmoduleSplurty.Viewdo
239 | usePhoenix.View,root:"web/templates"
240 |
241 | # The quoted expression returned by this block is applied
242 | # to this module and all other views that use this module.
243 | usingdo
244 | quotedo
245 | # Import common functionality
246 | importSplurty.Router.Helpers
247 |
248 | # Use Phoenix.HTML to import all HTML functions (forms, tags, etc)
249 | usePhoenix.HTML
250 | end
251 | end
252 |
253 |
defcsrf_token(conn)do
254 | Plug.Conn.get_session(conn,:csrf_token)
255 | end
# Functions defined here are available to all other views/templates
256 | end
257 |
258 |
259 |
260 | Save the file.
261 |
262 |
263 | Add a hidden form field to pass through the CSRF token when the form is submitted by adding this line to the web/templates/quote/new.html.eex file:
264 |
289 | Navigate to localhost:4000/quotes/new and refresh the page. Then fill out the form and press the submit button. The error message changes, and indicates the problem now is that the controller action is undefined. This means we've properly dealt with CSRF.
290 |
291 |
292 |
293 |
294 |
Adding the create action
295 |
296 |
297 | We'll need to add an action that will be triggered when someone pressed the submit button on the new form. Edit web/controllers/quote_controller.ex and add the create method, which will create a quote in the database and redirect the user to the index page:
298 |
332 | Save the file. Navigate to localhost:4000/quotes/new, fill out the form and press the submit button. You will be redirected to the index page and see the quote you just added displayed on the page.
333 |
334 |
335 |
336 | Your application should look
337 | just like this at this step.
338 |
121 | Our web application supports most of the standard CRUD functionality, but we haven't tackled deleting content from our database yet. We will do that in this lesson.
122 |
123 |
124 |
125 |
126 | From our web application we'll want to trigger a DELETE HTTP request to the quote_path in our application. Rather than doing this through submitting a form, we should trigger the HTTP request by clicking on a link.
127 |
128 | Unfortunately, right now Phoenix doesn't support links to non-GET requests out of the box. We can pull in a JavaScript library to do this for us called the RestfulizerJs.
129 |
130 |
131 |
RestfulizerJs
132 |
133 |
134 | Add the RestfulizerJs to your Phoenix web application. To start with copy the jquery.restfulizer.js file into priv/static/js folder.
135 |
136 |
137 |
138 |
139 | We'll also want to include jQuery, so let's pull that into our application too. We should place this within the web/templates/layout/application.html.eex file, so the JavaScript is loaded on all pages of our web application.
140 |
141 |
142 | Pro-tip!
143 |
144 | The application.html.eex is like application.html.erb in rails.
145 |
146 |
147 |
148 | Add the following two lines to web/templates/layout/application.html.eex:
149 |
157 | In order to activate the RestfulizerJs plugin, and also tie in our CSRF token we'll need to add a bit of JavaScript code. Including this script tag to the web/templates/layout/application.html.eex will do the trick:
158 |
220 | Save the file and refresh the index page. You should notice a destroy link got added. Sweet!
221 |
222 |
223 |
224 |
225 | In the code above, by giving the link the class of rest we connect it to the script tag we used above to configure the RestfulizerJs library. The data-method attribute tells RestfulizerJs to perform that type of an HTTP request when the link is clicked, in this case a DELETE request.
226 |
227 |
228 |
229 |
230 | When you press the destroy button you will be presented an error message, stating that we haven't implemented the action in the controller yet. Let's add the action in our controller!
231 |
232 |
233 |
234 | Add the method to web/controllers/quote_controller.ex so the file looks like this:
235 |
301 | This code uses the standard code we've been using to load up the Splurty.Quote model in the controller. We then delete the item from the repo in the same manner we used in Lesson 3. The user is redirected to the index of the QuoteController.
302 |
303 |
304 |
305 |
306 | Press the destroy button. Sweet! You will be redirected to the index page and the item you deleted will no longer be presented to you in the table.
307 |
308 |
309 |
310 |
311 |
312 | Your application should look
313 | just like this at this step.
314 |
61 | 
158 |
159 | 
150 |
151 | 
