We will be using the Homebrew package manager for installing all the Phoenix dependencies for macOS. So if you don’t have Homebrew installed, go to https://brew.sh and copy paste the install script on your terminal to install it. While Homebrew is not a prerequisite for Phoenix or Elixir, it helps us to install everything we need from the comfort of the command line.

The above command installs the latest stable version of Elixir along with Erlang. At the time of writing, this installs Elixir 1.4 which is what we need.

On Ubuntu and Debian

We need to install Erlang and Elixir individually.

Download the Erlang package and install it.

Now you can install Elixir using:

Phoenix projects by default are configured to work with the Postgresql database, though, any database that is supported by the Ecto library will work. We can also use Phoenix without any database if we need to. In this book, we will use the Postgresql database as it enjoys good support in the Elixir community. In addition to being well supported it also has features not provided by other databases that we will require later.

Once installed, Brew will print post installation notes as shown below:

Be sure to run either of the commands shown above as per your need. Normally, I run brew services start postgresql so that I can forget about starting the Postgres server every time I restart my system.

Brew installs Postgresql and creates a default super admin. The name of this super admin is the same as the name of your currently logged-in system account name while the password is left empty. We could just go with that. However, for every Phoenix project that we create, we need to modify the configuration file to give the right credentials for the Postgres database.

Phoenix projects by default expect the Postgres admin username to be postgres with the password postgres. We can save a few key strokes for every new project by creating a Postgres user as expected by Phoenix. Login to Postgres shell by typing psql -d postgres on your terminal.

On the Postgres console, type the following commands to create a super user by name postgres with the password postgres.

On Ubuntu and Debian

Install postgresql and postgresql-contrib through apt-get as shown below:

Ubuntu installation of Postgres creates a default super admin in the name of postgres but doesn’t set the password. So you might want to set the password to postgres on your local machine to match the default settings for Phoenix projects. Login to Postgres shell by typing sudo -u postgres psql postgres on your terminal.

Phoenix projects by default are setup to use Brunch — a nodejs tool for the management of asset files. In the development environment, all static files like images, fonts, CSS and Javascript files get processed by Brunch before Phoenix serves them. In the production environment we can use the precompiled files from our development machine without having to use Brunch on the production server.

Even in the development environment Brunch is not a hard dependency — meaning if we don’t want Brunch we can simply remove a simple configuration line in our project and still have Phoenix continue to work. Or we could replace Brunch with other tools like Webpack if we prefer. We will install Nodejs as we will use Brunch for managing the asset files in the development environment.

In the development environment, Phoenix provides live reloading feature that automatically refreshes our browser tabs whenever we change the source code in our project. On linux machines, this feature is dependent on inotify-tools while it’s not needed on macOS or windows.

Install inotify-tools using the command shown below:

Hex is the package manager for Elixir libraries. It allows us to upload/download Elixir libraries from the https://hex.pm website.

rebar and rebar3 are Erlang build tools for compiling and testing Erlang applications. Since our Phoenix project will depend on some of the Erlang libraries, we need Rebar to be installed on our machine.

mix is a command line binary that gets installed as part of the Elixir language installation. Since this is a sub-command of mix, a binary installed in our system as part of installing Elixir, the above command to install hex and rebar is same for all OS.

And finally to install the Phoenix project generator, run the following command:

It’s important to note that the above command installs the Phoenix project generator and not Phoenix itself. After installing the Phoenix generator, all that we get is a new sub command to mix, to create a new Phoenix project. The Phoenix framework itself gets installed within our project directory under the deps folder when we run the mix deps.get command which we will see shortly.

Run the following commands on the terminal to confirm you have installed the correct version of Elixir, Phoenix the required dependencies.

Elixir version should be 1.4.0 or higher.

Phoenix version should be 1.3.0 or higher.

PostgreSQL version should be 9.4 or higher.

Node version should be 5.0.0 or higher.

For a good developer experience, we will need a code editor that supports syntax highlighting and auto code completion for Elixir. There are several text editors that support the Elixir language. My personal choice is the Atom editor.

If you are a die-hard Emac or Vim fan, you might want to check out Spacemacs. For the rest of us, Atom works as a good editor for working with Elixir projects.

If you go with Spacemacs, do install the excellent Alchemist package for Elixir. It provides syntax highlighting, code completion and several other features that help your development workflow with Elixir projects. If you are on Atom, you can install language-elixir and atom-elixir packages to do similar stuff in Atom. The Atom packages can be installed from the terminal with a single command.

If you are not a fan of either of these editors, pick up one that suits your taste, but make sure that it at least supports syntax highlighting for Elixir.

The top level directory assets contains css, js, images, fonts and any other static files within respective sub folders. While the assets directory contains the original source code for our assets, the priv directory contains the compiled version of the same asset files. The priv directory is also the place where translation files and database migration files get stored. We will dig into these files more in the coming chapters.

The config directory contains files that store various configurations for our project like the database credentials, port number of the web server etc. Phoenix projects by default are configured to support three different environments — dev, test, prod.

Configuration files for each of these environments are present in the config directory as shown below:

The test directory contains the various test code for our projects. We will create files in this directory when we start with Test Driven Development.

The lib folder contains our project’s main code.

We will spend most of our time within the lib directory. All code that is specific to our project belongs here. This directory contains two subdirectories: first with the same name as our project and the second with a web suffix to our project name i.e., lib/learn_phoenix and lib/learn_phoenix_web

The learn_phoenix_web directory is the home of the web interface specific code for our project. That is, the learn_phoenix_web directory contains code for starting web server, defining routes, controllers, HTML templates etc.

All non-web related code go into the lib/learn_phoenix directory. This includes the context and schema files for our project. We will look into these in detail in Chapter 3.

Elixir has powerful metaprogramming features. This allows you to create Domain Specific Languages (DSLs). Frameworks like Phoenix make extensive use of meta programming in Elixir. For example, Phoenix router has several DSLs for defining routes.

Learning meta programming is not an overnight task. Even if you understand the concepts and syntax behind metaprogramming, it takes a lot of practice and experience to use it appropriately. However, the good news is that as a developer using Phoenix, you only need to grok a very small subset of metaprogramming and you don’t have to do it on a day to day basis.

In fact as a developer using the Phoenix framework, you will reap the benefits of the built in meta programming, without having to know how it works. The only time you may want to do jump into hard core metaprogramming is when you want to create a framework like Phoenix itself.

Apart from the metaprogramming feature in Elixir, the bag full of tools and concepts from Erlang OTP available in Elixir is yet another challenge for newbies to understand.

The Process, Agent, Genserver, Supervisor are a whole new paradigm shift for any programmer diving into Elixir. These concepts don’t exist in any of the mainstream web programming language. As a result the programmer is not just learning a new syntax, but is undergoing an entire overhaul in the way they think.

Again, you are not likely to use OTP tools for every single problem you solve in Phoenix. The Phoenix framework depends heavily on OTP, but not all your applications using Phoenix are likely to use the OTP tools heavily. In fact, you can even build a moderately complex application without knowing the abc of OTP. When you are comfortable playing with Phoenix, you can go back to OTP and learn it inside out.

Here is what I recommend as the learning path.

The above topics should cover you in most cases when working as a Phoenix developer. When you are comfortable writing simple projects in Phoenix, you may then venture into learning in-depth metaprogramming, OTP in Elixir and even Erlang itself.

In the following sections of this chapter, you will learn Elixir using the learning path outlined above.

For those coming from OOP background, remember that Elixir is a functional programming language and you cannot expect things like

Instead, you will normally find something like below:

When I first looked at this code, my immediate reaction was why should I type User twice? Why can’t I call the send_confirmation_email method on the user object?

As a functional programming language Elixir doesn’t have objects which are a mixture of data and behavior. In Elixir, you have to keep the data and the functions separate and there is no way data can come with a set of related functions.

So in the Elixir code above, User is a module, a namespace, which holds the user related functions. The function send_confirmation_email is created inside this module because it does something related to a user. However, it doesn’t have information about the specific user to whom it will send the email. This information has to be supplied at the time the function is called.

So when we say, Elixir is functional and that there are no objects, what we are effectively saying is that you can’t do "hello world".length in Elixir i.e., you can’t encapsulate data and the actions that can be executed on that data into a single object. In Elixir, data and functions live separately but go well together.

If you are coming from Ruby on Rails, do expect to type more than you are used to in your Rails project. Things are verbose in Elixir and consequently in Phoenix. Explicitness is encouraged and valued.

Take for example the simple index action of the PageController that we saw in the previous chapter.

If the same code is written in Ruby on Rails, it would be

Comparing both versions, the Phoenix version is explicit. The index action of Phoenix explicitly says that

While it’s more typing than its Rails counterpart, the above information is more valuable because its meaning is clear at a glance.

Because of language features such as pattern matching and pipe operators and because the framework values explicitness, you need to recalibrate your eyes to scan through the code easily. Here is a simple controller action for updating a cart in an ecommerce site. If you are not used to pattern matching and pipe operators, this code might look complex.

However, it’s only a matter of practice and time before you will fall in love with writing and reading code like this.

Being able to easily and confidently scan through a piece of code is an important measure of expertise. So how do you get this visual familiarity? Read through various open source Elixir code and practice. There is no shortcut ;-)

I hope I didn’t scare you away from learning Phoenix. My intention is to give you informed expectations in order to: help you learn Phoenix, appreciate things as they are, and to prevent you from struggling with an expectation-reality mismatch.

My wife is a Mammogram technician. She once shared with me something she learned from her experience with patients. Most people who undergo a mammogram procedure experience a significant amount of pain and many are not co-operative with the technician during the process. However, when my wife started explaining to patients what kind of pain they might experience during the procedure, reassuring them that it’s normal, and instructing them on the benefits they get in diagnosing medical illness, she started noticing something different. The patients are now more co-operative during the procedure and even experience less pain.

Learning a new language or framework works exactly the same way. The moment we face difficulty without being informed ahead of time we start to struggle, we get frustrated, and problems become more acute. But if we know what we face up front, then we "experience" the pain less, move forward earlier, and start seeing benefits sooner.

Atoms are constants whose name is their value. Atoms start with : (colon). If you are coming from Ruby, it’s the same as :symbol but with an important difference. Atoms are not garbage collected. That means if we create an Atom in our program, it lives forever.

An Atom on it’s own is minimally useful. In practice, it’s often combined with another data type such as a Tuple.

Tuple stores a collection of data. Items in tuple are comma separated and the entire data is enclosed within {}.

The Tuple is the de-facto data structure in functions that need to return more than one value. For example, Elixir’s built-in function File.read returns the Tuple {:ok, file_content} when the file read is successful; it returns the Tuple {:error, reason} when there is an error in reading the file. In this case the function File.read needs to return two values and it makes use of the Tuple to do so.

Atoms are mostly paired with Tuple data to annotate the type of data that is being stored in the tuple. By convention, the first element of most Tuples is an atom, though it’s not a necessity.

List also stores a collection of data. Items in the list are comma separated and the entire data is enclosed within [].

Both Tuple and List data types are used to store a collection of data. The difference lies in how the Elixir language implements them internally.

In practice, we use a List to store collections when we don’t know the total number of items in our collection ahead of time. For example, if we are parsing a CSV file, we will use a List to store the items from the CSV file. This is because the total number of items in the CSV file can vary.

Tuples on the other hand are used to store collections of known size. Return values of functions are a perfect example. We know ahead of time how many items we will return from a function and we can use Tuple for this purpose.

Keyword List stores one or more (key, value) pairs.

Internally, Elixir uses a List of two element Tuples to build a Keyword List.

To verify, let’s type a List of two element Tuple, whose first element is an Atom.

Since, a Keyword List is just list of tuples under disguise, the keys in the Keyword List can be repeated.

Like Keyword Lists, a Map is a data type for storing one or more (key, value) pair. Unlike Keyword Lists, keys in a map cannot be repeated. If you are familiar with Python, an Elixir map is a Python dict. Or if you are familiar with Ruby, it’s a Ruby hash.

A map is created using the %{} syntax.

Map keys can be atoms, strings, or mixed.

Structs are maps that have a predefine set of allowed keys. The Struct is the most commonly used data type in Phoenix for representing business entities. Since structs need a module definition, which we have yet to see, we will explore the struct data type after an introduction to Elixir modules in the subsequent section.

We have already seen the Math operators +, -, *, /. Let’s quickly run through the other operators.

Equality

==, !=, === and !==

Comparison

>, <, >=, ⇐

Logic

and, or, &&, ||

Elixir considers any value other than false or nil to be true. There is a subtle difference between and and &&. The and operator requires the left side operand to be either true or false while the && operator can accept any operand. The same difference applies to or and ||.

If you try to use and or or on a non-boolean left-operand, you will get an error.

Negation

! and not

Concatenate

<> is a concatenate operator that works with binary data. It joins two binary data into one.

Other Operators

There are other important operators such as the = (match operator), the |> (pipe operator), and the _ (ignore operator). We will explore them in detail in the subsequent sections of this chapter.

A Module in Elixir is used to group a bunch of functions doing logically related tasks. A module is defined using the syntax defmodule followed by the module name and a do.. end block.

From the Elixir docs:

Module names should begin with an initial capital letter and by convention use CamelCase. By the above rule, myModuleName, 111Module are invalid as they don’t begin with uppercase ASCII letters. My_Module_name is a valid module name but we will rarely see an Elixir library using this notation as the convention is to use CamelCase. So instead of snake_case My_Module_name, we will use CamelCase MyModuleName.

Let’s create a new module Catalog in our learn_phoenix app at lib/learn_phoenix/catalog.ex with the code below:

We have now successfully created a new module but it doesn’t do anything useful yet. So let’s look into writing some functions to do something useful.

We define functions inside of a module using the syntax def or defp followed by the function_name, followed again by a do…​end block. Functions defined using def are public functions whereas those defined with defp are private functions.

Public functions can be called from outside the module defining them whereas private functions can only be called within the module that defines them.

Let’s create a public function in our Catalog module to list some products.

The function list_products returns a List containing three product names. Like Ruby, functions don’t have an explicit return statements. The output of the last executed line of a function is its return value. In the above case, the last executed line is the List of 3 elements and the same is returned by the function.

Let’s try calling our function in the iex shell. This time we will run iex with -S mix argument from inside our project folder.

The above command runs the iex shell as usual but additionally compiles all the modules in our learn_phoenix project and makes them available in our shell.

The parenthesis after the function name is optional.

Let’s write another function in the Catalog module that returns a random product from the list.

Before I explain what is happening here, let’s go back to iex and call this new function.

We are greeted with UndefinedFunctionError. This is because when we started the iex shell, we didn’t have this function in our module. iex is only aware of the modules and functions that were present when we started it. To reload a module definition, we need to explicitly tell iex to recompile the module file.

Now we can call our new function as the module is recompiled.

Let’s go back and study our new function.

random_product takes a List as argument and then it calls the Enum.random function passing in the List. Enum.random is a built-in function that picks a random value from a List. Though our code seems to be working fine, it’s brittle because it makes the assumption that the input to random_product is always a List data type. What happens if we pass in a string?

Obviously, the string "hello" is not a List and our function random just passed on the input to Enum.random without validating the input. We can correct this now by introducing guard clauses to our function. Back to the code editor, modify the function as below:

Guard clauses are written after the function arguments but before the do keyword. In the above code, we are using a function is_list to check if the input is of type List. If so, the function returns true otherwise it returns false. If the guard clause returns false, then the function is ignored and not called.

Recompile the module again in iex and try again.

While the guard clause prevented the function from being called, it just resulted in a no function match error. What we ideally want is to return a tuple with two elements {:error, "Not a list"} when we give a non-List value as the argument. While we work at this, we also need to handle the case when random_product function is called without any argument. In this case it should return a tuple {:error, "Need a List of products as argument"}

Go back to editor add two new functions.

At first glance, this new addition looks like an error. How can we have multiple function definitions with the same name? Doesn’t one overwrite the other? In Elixir this is valid code and it doesn’t overwrite anything. We can write multiple functions with the same name as long as these functions either take different arguments or have different guard clauses.

Let’s now try all possible scenarios in iex shell.

So far we have referred to functions by just their name. But the proper way to refer to Elixir functions is function name followed by / followed by a numeral which refers to the number of arguments the function accepts. The proper way to refer to our functions is

Notice that there is no way to differentiate the two variations of Catalog.random_product/1 function i.e., the one with the guard clause and the one without it. The reason is Elixir combines these two functions into a single function with a case statement during the compilation process. We will see more about case statement in the next section along with other control structures in Elixir.

Before we wind up our intro to modules and functions, we will look into one of the exciting features of Elixir which is its built-in documentation.

In iex type in h Enum.random. Tada! You get the full documentation for using the Enum.random/1 function right on your screen.

Isn’t it cool? Let’s try looking for documentation for a couple of others like is_list or Enum.

In each case, Elixir gives us complete documentation of the function or the module. Can we try the documentation for our module and functions?

How does the documentation for Elixir functions work? How can we add this functionality to the code that we write?

Elixir provides first class support for documentation. We can document our module using the @moduledoc attribute in our module file followed by a multiline string which is enclosed by """ in Elixir. A function can also be documented using the @doc attribute followed by a multiline string just before the function definition.

Our modified module code with documentation for both the module and its functions look like this.

In iex, we can now read the documentation for our module just like we can read the documentation for any built-in Elixir functions. Reload the module in IEx and type in h Catalog or h Catalog.list_products and you will see the documentation on your screen. Isn’t that cool?

Our Catalog module is currently listing the products as a List of String data. Catalog is limited from expressing complex product information such as the product name, price and so on by the use of the String data type. Instead of using String data, we could make use of the Map structure.

Instead of this

We could write

However, nothing prevents us from having a typo in our product map. So instead of %{name: "Potato"}, we could have a typo %{naem: "Potato"} and this error goes unnoticed until run time, when a call to the name key throws an exception.

To avoid this, we need a data type that gives a compile time guarantee. We need it to catch errors during compile time or to put it another way if the code compiles it works.

Struct comes to the rescue for this situation. Structs are defined inside a module and take the name of the module in which they are defined. Let’s create a new module at lib/learn_phoenix/product.ex with the following content.

Now back in our catalog module, we can replace the maps with structs

If we have a typo in the keys such as %Catalog.Product{naem: "Potato"}, we will get an error right at the time of compilation helping us catch bugs and prevent them from creeping into production code.

In most languages, when we say a = 5 it means assign the value of 5 to the variable a. That is, the = is an assignment operator; it assigns the value on the right side to the variable on the left side of the operator.

However, = sign in Elixir is not an assignment operator but a match operator. In Elixir, when we say a = 5, what we are asking is to match the value on the right side of the operator to the variable on the left side. In other words, set the value of a to match the value 5. So, the value of a becomes 5 but this change is the result of matching a pattern. At this point, you might think it is same as assignment. That is because, we took a very simple example. Let’s look at a few more examples.

Open IEx to play with pattern matching.

Nothing new so far.

What happened here? We haven’t assigned any values to the variables a, b and c but Elixir matched the left side of the = operator containing a list of three variables to the right side of the operator containing a list of three values in a sequential order. Thereby the variables a, b & c get 1, 2 & 3 values assigned.

For the = operator to pattern match, items on both sides of the operator should be matchable. For example, if we ask Elixir to match [a, b] = [1, 2, 3], it cannot, because the number of items in the list on both sides are not equal.

We could either ask to match a = [1, 2, 3] in which case the entire list is assigned to a or we could give a list of [a, b, c] matching the items on the right.

Pattern matching can be done for all kinds of data. Let’s look at matching a map.

In line iex(2)> above, on the left side we have a new map with keys matching the keys of our user map. The = operator looks for matching keys on either side and assigns the value to the variables on the left side map corresponding to the value on the right side map.

_ (underscore) is the ignore operator in Elixir and goes hand-in-hand with pattern matching. Going back to the first example, what if we only wanted to know the second value of the list and not others?

We could rewrite the above to capture only the second value by using the _ operator.

Because we only need the second value, we replaced the others with _ which basically says "I need some value here but I don’t care what it is".

You can think of _ operator as a variable which forgets its value immediately after it’s assigned and goes back to its unassigned state.

Let’s check it out.

You can also use ignore operator as a prefix to a named variable to inject forgetfulness to it.

The above code works the same as using just _. The reason we might need this style of ignoring variables is to give some context to the programmer reading the code on what is being ignored. Consider the following tuple:

The tuple contains two elements. The first one denotes the role or position held by the person and the second one is the name of the person. If we want to get only the name through pattern matching, we can write it as follows:

The above code is more explicit than just using _ to ignore the first item. Just by looking at the code, we can say that we are ignoring the first value in the tuple which is storing possibly a value representing the role held by the person.

As we saw earlier, Tuples are normally used in functions to annotate the return value. For example, Elixir’s built-in function File.read/1 returns a Tuple {:ok, file_content} on success and {:error, reason} on failure. If we are using the File.read/1 function in our program and we need to execute different branches of code based on the return value, case is a suitable candidate for this task.

The case statement uses pattern matching to find the correct branch of code to execute. It checks the value of the expression right after case and tries to match the value with the different patterns within the do …​ end block. The code within the first pattern that matches gets executed.

We can have any number of pattern within the do..end block. We can also use _ operator as a pattern to match any value which is useful for a catchall case.

case is useful for a single expression which can output multiple patterns. Sometimes we might want to check multiple conditions with different expressions for a single operation. For example, let’s take the classic blog post example.

Here we have one operation which checks if the post can be edited or not and we have multiple conditions to determine the answer.

We stack all conditions inside the do.. end block and whichever condition returns true first gets executed. For this reason, we explicitly set the last condition with the block to true so that it gets called when all other conditions return false. In the above code, if the user is neither admin nor author, the last statement gets called which returns the value false. The return value of the cond statement is now stored in the can_edit variable.

Elixir also comes with handy if and unless constructs to check a single condition. if works as in any other language. It basically checks for a condition and if the condition returns true, then it executes the code.

Internally Elixir converts the above code to a case statement such as this

Elixir considers both the boolean false and the atom nil to be falsy values. Everything else is a truthy value. So in the above transformation of the if statement to a case statement, Elixir first checks if the expression matches any of the falsy value. If so, then it does nothing. For everything else, it executes the code given in the original if block.

The unless construct works similar to if with the twist that its code block gets executed when the condition returns false.

Here is the code from the PageController of the project created in Chapter 1. Look at line 2 of the module where it says use LearnPhoenixWeb, :controller.

This is a common pattern that we will see in many places in our Phoenix projects. It’s used to add a piece of common code to one or more modules. Let’s look at how it works.

Open the referenced LearnPhoenixWeb module. It reads as below:

When module A uses module B, module A calls the __using__/1 macro defined in the module B at the time of compilation. Here our PageController module has the line use LearnPhoenixWeb passing in an additional argument :controller and so it calls the __using__ macro defined in the module.

In the above example, __using__ macro checks the incoming argument value for the parameter which and calls the function by the same name inside the module LearnPhoenixWeb. We are passing in :controller as the value for which and so the code in controller/0 function gets called.

The controller function has the following code

The code inside the quote do..end block is called in place of the line that calls this function making the PageController read as below during the time of compilation. The line use LearnPhoenixWeb, :controller vanishes and in its place, we have 4 lines of code. It again has a use call, which the compiler will expand recursively until it finds no more use that can be expanded.

The injected code again has a use call, which the compiler will expand recursively until it finds no more use that can be expanded.

Without the use macro, we will be required to type several lines of code by ourselves in all controller modules. The use macro takes care of this rote task for us.

A program like a web application can have several points of failure. Elixir which is built on the Erlang Virtual Machine uses the Erlang feature called OTP to build fault tolerant applications. We do this by commissioning workers to do different tasks and putting them under different supervisors whose only job is to check if the worker processes are alive or dead. If any of the worker process is dead due to any failure, the supervisor’s job is to create a new worker in its place.

Our Phoenix web application needs a database and needs to start its own embedded web server to serve the web requests. Both these activities can potentially fail due to various reasons. The database server may be busy or temporarily down and the web server may crash due to a run time error. Whatever error happens, we need to ensure that our application recovers from it gracefully on its own.

The chart that we saw in the Observer window is the hierarchy of supervisors and workers as required by our application. Our application also depends on several other applications that we have mentioned in our mix.exs file. These applications also have their own hierarchy of supervisors and workers to carry out their tasks. This is the reason you see different supervision tree under each of the applications listed in the left sidebar of the observer window.

If we visualize this all together, it might look like a cluster of several independent trees like below:

How does Elixir or the Erlang Virtual Machine get the information about these tree structure? The answer to that starts with the mix.exs file. Back in our mix.exs file in the learn_phoenix project, we have among others, the following function.

The function application/0 is special. The information returned by this function is used by mix to generate a learn_phoenix.app. If you are brave enough, you can look at the contents of this file which is a large complex Tuple, reproduced below:

The file is present at this location _build/dev/lib/learn_phoenix/ebin/learn_phoenix.app relative to our project directory.

This large Tuple contains all the information needed to start the OTP supervision tree. To keep it simple, without going into the details of this Tuple structure, we will read the application/0 function again.

It returns a Keyword List with the key mod: holding the value {LearnElixir.Application}. This piece of information says whenever our application is started, call the start/2 function defined in this module. It’s like the main function in the C language which gets called first whenever you start the program.

This function starts the supervision tree for our project learn_phoenix. Without going into the details of how Supervisor.start_link/2 works, we can infer that it starts two child supervisors LearnPhoenix.Repo and LearnPhoenixWeb.Endpoint. Each child supervisor then has to define the workers and supervisors in its module. In this fashion, the supervisor tree of our project learn_phoenix gets generated.

Every Elixir project contains the mix.exs file and if it starts an OTP supervisor, it mentions the main module that is responsible for starting the tree. This is true for all the dependencies that we have listed in our project’s mix.exs file.

Elixir starts the supervision tree for each of the listed libraries above and this results in the cluster of trees that we saw above.

The ecommerce store that we will build is for a fictional brick and mortar shop Mango in the city of Auroville. The shop sells fresh vegetables and fruits to its customers directly sourced from nearby farms. Due to popular demand to reduce the carbon footprint, Mango has decided to open an online store for its customers. However, the management still wants to continue operating the physical shop for customers who prefer to visit the shop in person. Also the online store only accepts orders from residents of Auroville and delivers to only locations inside Auroville.

As a customer, I want to

As an admin, I want to

Developing a blog app or a simple Twitter clone to understand Phoenix is a good start but to fully appreciate the benefits of increased complexities introduced by Phoenix Context since version 1.3, we need to develop something that is much bigger than a few CRUD operations. Our completed app will contain the following contexts.

Throughout this book we will be using the Hound library to interact with our HTML programmatically. Let’s spend some time understanding the basics so that when we use Hound in subsequent chapters we don’t have to diverge too much from what we are doing to understand Hound’s syntax.

Think of Hound as your little assistant who likes to do rote tasks. First, you teach Hound a given task. Then later you can ask it to repeat the task after you make modification to your code and it will repeat the task with pleasure. The type of tasks you can automate with Hound are

This is a non comprehensive list of tasks that Hound can do. To read the comprehensive list of tasks, have a look at Helpers section in the API Documentation.

The above list of tasks gives us an idea about Hound’s abilities. Hound can do the job of manual testers. Manual testers are typically given a list of tasks to accomplish, and do so by opening a browser and check them off one by one. Hound does this programatically.

Let quickly review some of the basic Hound commands that we will use quite often as we move through the book.

Most of the names are self explanatory. We will quickly go over each command below to ensure our understanding:

Visit Page

All Hound commands are given in the context of a webpage. So the first thing that we will want to do is to visit a page. We can instruct Hound to visit a page by using the command navigate_to("/path_to_visit")

Finding Elements

To interact with the webpage, we need to first identify the element on the page with which we want to interact.

Consider the following HTML document displaying two pieces of product information:

We can use Hound to find the first product by using find_element(:css, "#product1"). We can also find all products in the page by using find_all_elements(:css, ".product").

In the command find_element(:css, "#product1"), the first argument refers to the strategy by which we identify the elements. In this case, we are using :css strategy to find the elements so in the second argument we reference a valid css selector. #product1 is the CSS selector that we normally use to style the product element in CSS by its id property. We use the same selector here to find the element.

Next, to find an element which is a child of another element we use the find_within_element/3 function. It works similarly to how the find_element/2 function works but takes a parent element as an additional first argument. For example, to find the buy link of the first product, we can use find_within_element/3 like this:

Interacting with the elements

After we have identified an element we can interact with it. For example, we can click the element or read the elements visible text.

Extending the above example,

Interacting with the page

Sometime, we might need to interact with the page as a whole. Such as reading the page source to find out if some text is present or not. In such cases, we make use of page_source() which returns the complete HTML of the visited page as a string.

Let’s write our first acceptance test. Open a new file test/mango_web/acceptance/homepage_test.exs and write the following code.

The above code loads the / path of our app in the test browser and checks if the page contains the text "Seasonal products”. We are using helper functions provided by the Hound library to navigate to a given path and to check the presence of a text in the resulting page.

We need to start Phantomjs before running the test. On a separate terminal tab, run the following command to start Phantomjs.

Now on another terminal, run

to execute the test we have written.

Hound makes a request to http://localhost:4001 in Phantomjs browser and checks for the text "Seasonal products".

The test fails as the text "Seasonal products" is not present in our template. Again, this test simply checks for the presence of a chunk of text. To make this test pass we just need to add the text that our test expects to our homepage template.

Two problems you might encounter. First, if your test fails with a blank HTML body content as in the screenshot below, you most likely forgot to turn on the server for the test environment as explained above.

Second, if you get an error like below, then you might not have started Phantomjs in a new terminal as indicated earlier.

Add the following text to templates/page/index.html.eex

Now run the test again and it should pass.

From now on, whenever we run our acceptance tests, we need to ensure that Phantomjs is also running.

Let’s get started with our storage needs. We need to decide where to store the registration data and how we should represent this data in our application. As we saw earlier, we can store the data in a customers table and we can represent this data in our application using a %Customer{} struct.

The next thing we need to consider is the context module that will hold our API functions which will be used to interact with this struct. The context for this customer struct can be CRM (Customer Relationship Management). We chose this name for the context as we have already seen a full list of user stories for Mango which contains features such as the ability for the customer to create support tickets. Because we have these functionalities planned, the name CRM suits us well. CRM is a good context because it fits our current needs and can be extended to hold other customer related API functions such as our support tickets.

In the last chapter when we migrated our Product data to Ecto, we manually created both the migration file and the schema file in two different steps. We can do better by using the mix task mix phx.gen.schema to do it in a single command.

In the terminal, run the command mix phx.gen.schema followed by ContextName.SchemaName, table_name_in_plural, and a list of fields which are required in the table along with their their data type as shown in the command below.

The above command includes a lot of information and creates both the schema file and the migration file. Let’s understand what is going on.

Open the newly created migration file and confirm everything is configured as required.

All looks fine, except for the email field as our specification says

If we were to create a table as it is now, our system would consider data such as "JOHN@example.com" and "john@example.com" to be two different emails and would allow two different registrations with the same username.

Obviously we don’t want this to happen. So we need to modify the column definition of the email field from :string to :citext which is a column type supported by the PostgreSQL database for storing case insensitive strings. Additionally we need to enable the citext PostgreSQL extension as it’s not available without enabling it explicitly.

Modify the email field definition in the migration file as given below.

Let’s run mix ecto.migrate to execute the migration file.

Open customer.ex file created by our mix command to see the schema definition created.

It looks similar to what we have seen in the Product schema module except this one imports Ecto.Changeset and has a changeset/2 function defined in it. To understand this changeset, let’s open iex -S mix and start playing with it.

We were able to create a new customer with just the name value using Repo.insert. We need to restrict the struct from being inserted into the database if it’s missing required values? The solution is to use Ecto.Changeset.

If you are familiar with Rails, Changeset is similar to ActiveRecord validations. However, there is a lot of flexibility allowed with the Ecto.Changeset that is not provided by ActiveRecord. For instance, it’s very easy to provide different types of validations for a single schema without resorting to complex if else conditional trees.

Coming back to our Customer struct, let’s say we don’t want it to be stored without name and email field. To do that, we need to use Ecto.Changeset when inserting the data. Before we do that, let’s understand what Ecto.Changeset is.

As you can see from above, %Ecto.Changeset{} is a normal Elixir struct just like our %Product{} struct that we have created in the previous chapter.

The %Ecto.Changeset{} struct has several keys which can be seen in our second call to Map.from_struct. Without going into details regarding what these keys are meant to store, understand that we need to use this struct to insert data into our database when we want to perform any kind of validation on our data.

So, for inserting validated data; instead of using %Product{} |> Repo.insert or %Customer{} |> Repo.insert, we will have to use %Ecto.Changeset{} |> Repo.insert.

Because we use a common struct to insert all kinds of data in our database, there needs to be a mechanism to store our product data or customer data into this %Ecto.Changeset{} struct. Ecto provides several functions to create and manipulate %Ecto.Changeset structs. These functions are defined in the module Ecto.Changeset.

To insert our customer data into %Ecto.Changeset{} struct, we need to use the function cast defined in Ecto.Changeset.

Back to iex -S mix, let’s start using this cast function to create %Ecto.Changeset and insert customer data in it.

The cast function takes 3 arguments and they work as described below.

You can think of the cast function as a funnel that takes an input map, filters only the allowed values and stores the struct and filtered values in the %Ecto.Changeset struct.

The above diagram explains the function of cast. On the left side of the =, we have %Customer{} struct, a set of values represented by green and red dots, and a filter that is in green. On the right side of the = we have the output of the cast function which is an %Ecto.Changeset struct. The struct returned embeds the entire %Customer{} struct as passed to the cast function and it contains only the green values as allowed by the filter.

Back to iex -S mix, we can try out different filters

In the first example, we passed a %Customer{} struct, a map containing name and email, and a list containing only :name which acts as the filter. The result is an %Ecto.Changeset{} struct. However, if we look at the changes key, we see only the name value appears.

This is because our filter given as the 3rd argument allows only the :name field to be changed.

In the second example, we did the same, but this time, we allowed both :name and :email by placing both values in our list of allowed filters. This gives us an %Ecto.Changeset{} struct whose :changes key includes both the :name and :email values.

The :changes key in %Ecto.Changeset{} struct contains the values that are allowed in the filter, whose value is different from the value present in the struct passed as first argument to cast.

Consider the following example

Even though we allow both :name and :email in our filter, the resulting changeset only contains :email value in the :changes key. This is because, the customer struct that is passed in already has the same name. So there is nothing changed from the original value.

It’s important to note that %Ecto.Changeset is just a pure data structure. It knows nothing about the database. The function cast also knows nothing about the database. It consumes a struct and returns a struct. That means unless we call Repo.insert or some other function in the Repo module with the changeset struct, the database is not touched. That is to say, Ecto does not make changes to the database.

Let’s try inserting some data using a changeset.

Now, let’s add more validation to our changeset. We want to insert our data only if the :email value is present.

We can chain these three steps using the pipe operator, which allows us to accomplish this without using temporary variables.

If we import the Ecto.Changeset module, the above code can be even more compacted

There are several validation functions present in the Ecto.Changeset like the validate_required function that we just saw. All of them take a changeset as input, validate the data present in the changeset and return a changeset marking it as valid or invalid. We will see more of these validation function as we work through the registration process.

Let’s go back to our work…​Where were we? Oh yeah! Customer schema.

With our recently gained knowledge of the Ecto.Changeset module, let’s try to understand the Customer schema module generated earlier.

Let’s use it in the IEx shell.

As expected, we get a changeset struct with all the errors listed in the errors key.

And when we pass all the required values, we get a changeset whose valid? value is true.

As promised we have spent a good deal of time understanding the Ecto.Changeset schema and function. Now let’s get into the task of creating the registration form.

We will start with an acceptance test.

Create a new file at test/mango_web/acceptance/registration_test.exs

Add the following test function that checks for a successful registration.

The test navigates to the /register path and fills in all the fields with valid data. We are using the :name strategy to find the elements and the fill_field function to enter the value.

Finally we submit the form and expect the "Registration successful" message on the homepage.

Now add this test for checking invalid registration.

View Gist of complete test file

We start again by navigating to "/register" and we submit the form without filling in any values. Then we expect to return back to the same path and find an error message. Of course, we could do better by testing if the error message for each of the field is as expected. However, that would be overkill for what we are trying to learn now. You can of course try to do that as an exercise.

To start with, let’s create two new routes for handling registration.

We will now add a new controller file registration_controller.ex inside lib/mango_web/controllers with the following content:

Create a new view file at lib/mango_web/views/registration_view.ex with the following content.

Finally add a new template file at lib/mango_web/templates/registration/new.html.eex with the following content.

Now visit http://localhost:4000/register` to see the message in our template.

Our registration form is going to create a new customer when submittted with valid data. When a form directly maps to a schema struct, we need an Ecto.Changeset. In our case, we need an Ecto.Changeset for our customer struct to create this registration form.

We don’t have our context module CRM created yet. We need two functions in this context for our current requirements. We will call them

The following are the requirements for the build_customer function:

Let’s start writing the unit test for these two functions with the above design in mind. Create a new file test/mango/crm/crm_test.exs file with the below content:

The first test is straight forward. Ecto.Changeset has several keys which we haven’t seen in detail. The :data key in the changeset stores the struct for which it is created. Here we are testing if the changeset returned is for the %Customer{} struct by pattern matching on the :data key.

The second test checks if the attrs passed in to build_customer are indeed applied to the changeset. We test this by checking if the :params of the changeset is the same as the map we passed into the build_customer function.

To pass both the tests, let’s create lib/mango/crm/crm.ex with the following code.

The \\ in the function definition sets the default value of attrs to an empty map %{}. This default value is used when we don’t pass in any value to build_customer. The rest of the code is what we have already seen. We are building a changeset for the %Customer{} struct passing in the attrs value.

Run mix test test/mango/crm/crm_test.exs to confirm everything passes.

Let’s modify the registration_controller.ex file to use this new function and then pass the changeset returned in to the template.

We will now modify this template to display a registration form. It basically needs an html form like below

However, instead of using the plain HTML form like above, we will make use of form_for html helper to generate the HTML form. Using form_for automatically adds hidden fields to the generated form with CSRF tokens that Phoenix uses to validate the incoming data. By default Phoenix enables CSRF protection so any form submission without valid CSRF tokens are rejected by Phoenix thus securing the application from CSRF attacks.

Modify the template to present a partial registration form.

Now visit the page to see the form rendered.

The form needs more elements but before we add them, let’s focus on understanding the code so far.

The above code using form_for block generates the following HTML

The form_for function takes

Within the anonymous function, we render

Let’s look at the helper to generate a single field.

All input helper functions take a form struct represented by f as the first argument and the input name as the second argument. Any attributes that need to be set on the HTML element are given as the third argument in a keyword list.

With this understanding, let’s add all the remaining fields. Our template will now look like this:

Back in the browser, our registration form is now complete.

Try submitting it, we will get this error.

That’s because we haven’t added the create action in our registration_controller.ex to handle the form submission.

Open the controller and add the create action as below:

How to retrieve the submitted form details from the params?

When a form is submitted, the controller actions receive the form contents as part of params in the second argument. Unless we know the structure of the form data present in params, it’s not possible to pattern match and isolate the submitted data from the form. All form submissions in Phoenix are received in the map format as %{ "form_name" ⇒ form_submission_data }, where

So to get the submitted data from our registration form we just need to pattern match on the key "registration". The result will be a map of our submitted data.

We can do this match on the function head as below:

We have the submitted data available within our controller as registration_params and what we now need is a function to create a customer with this value.

The function name can be create_customer accepting a map of our customer field values.

The requirements for this function are:

To satisfy the last condition, we need to make a couple of changes to our schema.

Add the following test to test/mango/crm/crm_test.exs file.

Open mix.exs file and add comeonin as dependency to the deps function and run mix deps.get to download it.

Open lib/mango/crm/customer.ex to make the modifications to the customer schema as discussed above.

We also need to change our changeset function in the same file to accept the value for the virtual field :password and to set validations for the other fields.

Now that we have removed the password_hash field from the casting, we need to set it manually with the hashed content of plain text password.

To generate the hash, we will use the comeonin Elixir library that we installed which uses a secure algorithm to hash the password.

With all those changes done in the Customer module, let’s create a new function in CRM context module to create a customer.

With this change, let’s check if our new unit tests for CRM pass.

All tests pass and now we could make use of our new functions in the create action of our registration controller.

We make a call to CRM.create_customer(registration_params) and we pattern match on the return value. If it matches {:ok, customer}, then we use put_flash to set the success message and finally redirect to the homepage. If the return value matches the pattern {:error, changeset} we render the new.html template passing the error changeset to template. The Phoenix form helpers automatically show the error in each field in the rendered template.

Now open up http://localhost:4000/register and submit the form without entering any values.

It will display the registration form again with error messages against each field.

Now run the test mix test test/mango_web/acceptance/registration_test.exs and we should have the test for valid form submission pass while the other fail.

Our invalid form submission test expects a message to be shown on the form if there are errors present. In order to get our Acceptance Test Passing we need to add this message. Open the registration template and add this code inside the form_for block.

The above code checks if the action value is present in @changeset. If present, it shows the message. The action value is set in the changeset when Repo.insert fails to inserting the changeset.

Now running the test again, both the tests should pass.

We will run our complete test suite to check ensure we did not introduce any regressions.

No errors. We are good to go so lets modify the registration form to satisfy the last requirement of our user story:

We can modify the residence_area field in the registration form as shown below to convert it into a select box:

The select function creates an HTML select box with the options passed to it as a list. In the above code, we are creating a select box in the registration form showing three options with the prompt "Choose your residence area" as shown below:

In a real world application, we would probably get this list from an external service that provides a JSON list of residence areas.

Third party integration code that are not specific to our application can be added as top level directories under the lib folder. Create a new file lib/auroville/residence_service.ex with the code shown below:

The folder lib/auroville serves as the context for our external integration code. In the above example, we have a hard coded list of areas. However, in a real world application, this list will be replaced with an HTTP request for an external API that provides the real-time list of residence areas. Elixir has several HTTP client libraries such as HTTPoison and HTTPotion. You may use them to get the list of areas from an external service. For example:

Now, let’s change the registration controller as shown below:

(1 - 4) — We are getting the list of residence areas from the external service module that we just created and we pass on this value to the template in both the new and create actions.

Let’s modify the template to use this value. Open templates/registration/new.html.eex and modify the residence_area field as shown below:

If we run our test now, the acceptance test for the registration form will be broken.

This is because our existing acceptance test treats the residence area field as a text box. We have now changed it to a select box in the registration form. So we need to modify the test file as well. Open test/mango_web/acceptance/registration_test.exs and modify the residence_area field as shown below:

Replace this line

With this line:

View Gist of the modified change in the test file.

Now run mix test and all tests should pass as earlier.

We will start with an acceptance test for capturing the details above.

In the setup, we create a new customer with valid details so that the following tests can be made in the context of this customer trying to login.

Add the following test to check login validity

Add the following test for invalid login.

As with registration, we need two routes: one for displaying the login form and another for processing the submitted data.

Open router.ex and add these two routes.

Create the session controller with the following content:

Create a new view at mango_web/views/session_view.ex with the following content.

Finally, create a new template mango_web/templates/session/new.html.eex with the following code.

In the previous section when we created a form for registration, the form fields directly mapped to the customer struct. But now, what we need is a simple form for login with two fields which doesn’t map to any struct. For this purposes, we need to use @conn struct for creating the form.

At this stage, we now have a login form displayed. Try visiting http://localhost:4000/login to see the login form.

The form submission still doesn’t work because we haven’t added the create action yet. Let’s do that now.

Open session_controller.ex file and add the following content.

We have already pattern matched the form data on the function header in the previous section on Registrations. We are reapplying the same concept here for getting the session data as well. Now what we need is a way to validate the password and sign the customer in.

Since the form submission contains the email of the customer, we need a way to get a customer record from the database using their email as our query.

Next, we need to validate if the password given in the form data matches with the hashed password of the customer. If it matches we return the customer; if not we return an error.

Let’s write the unit tests for the function get_customer_by_email which fetches a customer from the database using the given email. Open test/mango/crm/crm_test.exs file and add the following test.

The above test creates a customer and then uses the new function (that we will write subsequently) to load the customer by email. Finally we check if the customer returned by our new function is the same as the customer created in our test.

We will write a similar test for the function get_customer_by_credentials which will load the customer after verifying the given password. If the password matches the encrypted password, then the function returns the customer. Our test setup is similar, and we check if our new function will return the customer using the email and password used to create the customer.

See Gist of updated crm_test.exs

Let’s open the context file lib/mango/crm/crm.ex and add the following implementation code to pass the above tests.

Now we have all the API functions needed for performing a login. So let’s open up the session_controller.ex file and modify it as below. We will run through it line by line.

The session_params contains the email and password data entered by the user as an Elixir map. We pass this value to the function get_customer_by_credentials which will take care of validating the customer and password details given. Since we know the structure of the return value from this function, we now use a case statement to match the value and perform the appropriate action for either a successful or unsuccessful login.

For the unsuccessful attempt, we just put in a flash message and show the login form again. This is done by rendering the new.html.

For the successful login, we do a bit more:

If we now try to login with a valid credential, we will be logged in as shown in the screenshot below:

In the last section, we created the login form allowing the user to successfully login with valid credentials. We also stored the customer data in the conn struct as :current_user. However, since the conn struct values are reset for every page request, our current_customer value is not available for the next page reload. That means even though we have the id value of the logged in customer in the session data, our templates can no longer access the @current_user data.

Moreover, we can only make use of the data that we store in the conn through the assign function and cannot use the session value in templates. So that brings us to the question: how can we assign the value of current_user in the conn struct for every page request?

When we want to modify the conn struct in this way, the defacto way of doing it is to use a plug module. For a plug module to work, it needs to be added to a plug pipeline present in our app. Since we are learning several new concepts now, let’s take it one by one.

Let’s create a plug module first.

Any Elixir module can be called a plug module if it satisfies the following conditions.

Create a new file at mango_web/plugs/load_customer.ex with the following code which satisfies the above definition of a plug module.

The plug that we wrote will sit idly in our app unless we put it to use. We use a plug by adding it to one of the plug pipelines in our applications. The pipelines available are

We will understand what a pipeline is in a moment. For now, assume that it’s a place where you can put your plug module in order to access its functionality.

If you open up lib/mango_web/endpoint.ex file, you will see several calls to plug <this>. Snippet shown below:

We could add our plug module in the Endpoint list, but it’s not appropriate.

Endpoint plugs are meant to do low level grunt work like adding a logger, parsing HTTP request body etc. Our plug is meant to load our customer data which is very much application specific. So it’s not something that fits the Endpoint plug role.

Alternately, we could add our plug to any of our controller modules. But when added to a controller a plug only gets executed for paths that use that specific controller. Again, this is not what we need. We need the current_customer data to be available for all controllers.

The last option is to place the plug in the router pipeline so that any path using that pipeline will be able to call our new plug. This looks like what we need.

Open the router.ex file and add our plug to the code highlighted below:

A router pipeline is a list of plugs that are chained one after the other and is used by one or more paths defined in the router. In the case of our router, all routes defined with the scope "/" block use the above pipeline as configured by the line highlighted below:

Because of this configuration, all requests that pass through the scope "/" will call all the plugs listed in the :browser pipeline. Each plug receives a conn struct as input. Each plug also has the potential to change the value of the conn struct and return the newly updated conn. The updated conn value will then be used by the plug that follows. Since our plug is listed as the last one in the pipeline, the conn value returned by it will be passed to all controllers and then to the templates.

So if we check the customer_id in the session, load the customer for that id, and then assign it to the conn under the :current_customer key, then our controller and templates will be able to access this value automatically.

We don’t have a function in our CRM context to load the customer by id yet. Let’s define it before we move on to the plug.

The function takes id as an input and returns a customer record matching the id.

With all that set, let’s write a test for our new plug. Create a new file at:

with the code shown below:

To make this test pass, we will modify the LoadCustomer plug as follows:

Run the test for the new plug and it should now pass indicating that our customer information is now available in conn.assigns.

With all this heavy lifting by our LoadCustomerPlug, we can now work on displaying a menu specifically for the logged in user.

If the user is logged in, we display their name and show a Log out link, if not, we show links to the registration and sign in pages.

Open the layout file mango_web/templates/layout/app.html.eex and pass in the @current_customer value to our navigation partial.

In the navigation partial, we will display different HTML content based on the value of @customer. Modify the app_nav partial with the HTML shown below.

Now visit the site as a logged in user and you will be able to see the logged in user information in the nav bar.

Let’s start with an acceptance test. Create a new file test/mango_web/acceptance/cart_test.exs and add the following test code.

We can now run just the cart acceptance test by executing mix test with the file name.

It should fail now as there are no button elements in our product template yet.

Open product template at mango_web/templates/product/product_card.html.eex to add the cart form.

Also make sure to pass on the @conn variable to the product_card.html.eex template so that our cart form can access it.

Open page/index.html.eex and category/show.html.eex and modify the line shown below in both files by passing @conn.

Since we now have the expected "Add to cart" button on our product template, running our acceptance test again will now pass.

Let’s modify the acceptance test to actually test the functionality of adding the product to cart.

The modified test now finds the quantity field and changes the value to 2 and then clicks on the cart button. It then checks if there is a success message such as "Product added to cart - Apple(1 kg) x 2 qty".

To generate the message to verify after successfully adding a product to cart, it uses the two new fields expected in the cart form namely the product name and pack size field. We can use hidden fields to present this information in the form.

Since our product template is now growing in size, it’s good to refactor it by extracting the cart form to a separate template.

Modify the product template to include the partial.

Create a new partial cart_form.html.eex inside the product template folder with the content below.

Now if we visit the homepage, we should be able to see the Cart form displayed for each product with all the necessary fields:

Our add to cart form now submits the content to the /cart path. By default form_for submits using POST method. We don’t have this route yet. Let’s add it.

Create a new cart controller file at lib/mango_web/controllers/cart_controller.ex and add the following code. Some observations of the code are appended below the code.

There are quite a few missing pieces of code here. But we can start filling in blanks wherever we have insight about what is needed. Lets start!

Handling the success case

The function Sales.add_to_cart/2 doesn’t exist yet. Assuming it exists and returns a success tuple, we can put a flash message on screen as expected by our acceptance test.

Here again we resort to pattern matching to unpack the submitted data in distinct variable names. We then use the variables to construct the message using interpolation. Finally we redirect the user to the homepage and display the flash message.

Handling the failure case

In case the add_to_cart function returns a failure response we again redirect to the homepage, but this time we display a flash message explaining what went wrong.

Assembling all these pieces in our cart controller, we end up with this code:

HINT: It needs to exists before you find it.

As discussed earlier, the cart is nothing but an order in the "Cart" state. We will first create two functions

Once we have both these functions we will go about finding the current cart for a given user.

Let’s create our test code thereby setting our expectations for these two functions. Create a new test file test/mango/sales/sales_test.exs with the content below:

To pass the above tests, create a new file lib/mango/sales/sales.ex with the code below.

Run mix test test/mango/sales_test.exs to confirm the test passes.

With those two functions ready, we now get into the meat of our work. That is,finding the current cart.

What is current cart?