In this section, we will install all the dependencies for the Phoenix framework including installation of Elixir and Erlang. We will cover installation instructions for macOS and Ubuntu/Debian here. However, Phoenix can run in several flavors of Linux as well as in Microsoft Windows. For installation instructions related to other platforms, check out the official installation page for Elixir and Phoenix.

In this section, we will quickly run through the steps required to create a new Phoenix project and add a new page to it. This exercise is to quickly glance at the various moving parts of Phoenix and not to master them. So don’t worry if you find it difficult to understand the code or if all this seems too fast paced. We will spend adequate time in the rest of the book to build understanding.

Let’s create a new Phoenix project using the mix generator command phx.new. It is the new sub command to mix binary that gets added when we installed the Phoenix generator in section 1.1.8.

Open up your terminal and run the following code.

This command creates a new folder learn_phoenix in your present working directory. In my case, my pwd is ~/pio and the new Phoenix project is initialized in ~/pio/learn_phoenix folder.

You will be prompted to either download the dependencies or skip them as below.

Choose "Y" to download the dependencies. The installer will then proceed to download all required Elixir libraries from https://hex.pm (the official package manager site for Elixir projects). It will also download nodejs packages from https://npm.org, specifically Brunch and its friends which are used for assets management in Phoenix.

For now, it will suffice to know that the mix phx.new command has downloaded several Elixir libraries in your project’s deps folder and also downloaded several nodejs packages in assets/node_modules.

The contents of the assets/node_modules directory is too big to show here in full and not very relevant to what we are learing.

Now run mix phx.server from inside the project directory.

This will take some time as Elixir compiles all the Elixir source code from our project and its dependencies into .beam files. Once compiled, you will see the following message on your terminal.

There are several error messages and then a line that reads

Let’s ignore those errors for now and open our browser to http://localhost:4000. We will be greeted with Phoenix welcome page:

Now back to the errors that we saw in the terminal. Our application is trying to connect to a Postgres database which doesn’t exist.

Let’s fix this error. Hit CTRL+c twice in the terminal running Phoenix server to stop it. Open config/dev.exs file in your editor and check if the Postgres login credential given are correct and Phoenix has the privilege to create a new Postgres database.

If our local PostgreSQL username is postgres and password is supersecret, we need to change the database configuration in config/dev.exs file (shown above) to reflect the same.

However, if you followed the instructions to create Postgres superuser as previously explained in section 1.1.3, you don’t have to make any change in the config/dev.exs file.

After the database connection details have been configured correctly, we can now run mix ecto.create to create a database for our Phoenix app and then run mix phx.server. This time we won’t see those db connection errors as our Phoenix application is now able to connect to the database.

Our learn_phoenix directory looks like this:

We haven’t done anything with our new Phoenix project yet. Let’s try to understand how the welcome page works and then mimic the same to create a new page at http://localhost:4000/about.

My preferred way to read an MVC web app is to start at its router file. This approach makes it easy to understand the control flow of various paths.

The router file for our Phoenix project is at learn_phoenix_web/router.ex.

If you are familiar with any MVC framework, you might have at least guessed what this line of code means:

It basically says, for any request coming to / path (i.e., homepage), call the index function of the PageController. The controller functions that are mapped in the router for a specific path are also called controller actions.

Our PageController defined at learn_phoenix_web/controllers/page_controller.ex looks like this now:

The index action receives the control from router and it renders the index.html file.

Again if you are coming from Rails or another MVC frameworks, you might guess that this file exists in the views folder. However, it turns out that our learn_phoenix_web/views folder does not have any html template files. Rather it contains a file called page_view.ex which defines PageView module.

Looking around in the other generated directories, it’s easy to find the index.html.eex. It lives inside the directory learn_phoenix_web/templates/page/. The contents of the file also confirms that it’s the same as the one that we see in the homepage.

At this point it might be difficult to understand the purpose of PageView module as it is almost empty.

While it’s tempting to conclude that PageView does nothing, that is not correct. To understand it, let’s change the render function call in our PageController module as below:

Now if we visit the homepage, we are obviously greeted with an error. This error is however helpful to understand what is happening under the hood.

A layman’s translation of the error message is below:

Now instead of creating a new template index_new.html.eex in the template folder, let’s create a new function render/2 in our PageView module as below:

Now going back to our homepage, we should see the new message displayed as given in our PageView module.

We will now remove this render function from the PageView module and add just the html to a new index_new.html.eex file inside learn_phoenix_web/templates/page. Back to the browser, the result is the same.

So what is happening here? It’s Phoenix magic powered by Elixir’s metaprogramming feature.

When we call render(conn, "index_new.html") from our PageController we are calling a function defined in the Phoenix.Controller module. It then calls render("index_new.html", _) defined inside our PageView module. But we have just removed this function from the module. So it’s not there to be called and we expect an error.

Here is the nice little trick that Phoenix does. During compilation process, it looks for any template files in the template folder ending in .eex suffix. It then takes out the contents of each of these files and creates a render/2 function in the respective View modules similar to what we have created.

To summarize, the sequence of events happening when you visit http://localhost:4000/ are:

Now armed with this knowledge, let’s create a new page at /about. Based on knowledge gained so far, we know we need to do the following to complete our task:

Let’s modify the router as below to create a static page at http://localhost:4000/about.

Modify our PageController and add a new function as below:

Inside our learn_phoenix_web/templates/page, create a new file about.html.eex and add some HTML data.

Now back to the terminal and run mix phx.server if it’s not already running. Let’s open http://localhost:4000/about in our browser to see the message we added in our template file.

We have now learned how the request for a web page flows through various parts of our Phoenix app and how to create a new static page in our application.

Let’s recap on the key concepts that we learnt in this chapter.

We learnt to install the various dependencies of the Phoenix Framework for macOS & for Ubuntu/Debian OS. We also installed the Phoenix project generator which we use by issuing the command mix phx.new projectname

As with any other Elixir project, we learnt that the Phoenix framework is installed as one of the dependencies of our project inside the deps folder. Hence all Phoenix projects are self-contained with a version of Phoenix installed inside each project.

We also configured the database connection, got to know a few mix tasks and understood the file structure of Phoenix.

Then we moved on to understanding how a page request is served by Phoenix. We did this by looking at the various interconnected critical components of our project including the Router, Controller, View and Templates.

Along with this, we also understood the inherent naming conventions and how Phoenix automatically identifies and links Controllers, Views and Templates.

Finally, we flexed our muscle by creating a new static page and getting it served successfully.