Do you want to know the most important aspect of our partnership? It’s the transfer of that knowledge from you to us. We have so many clients say, “This stuff is easy!” or, “What we do is simple.” Let me tell you why this transfer is essential.

These statements are coming from someone who works in it every single day, thinks about it all the time, and for how many years now? Wouldn’t want your software team to think and feel like they are in the weeds on the daily as well? We need your help to bring us up to your level so that we can make more informed decisions in the development and design processes. Every line of code is a decision and the more frequent access we have to clients, the better the decisions are and the quicker the feedback. This should be an iterative process intended to build shared understanding throughout the engagement.

Now What happens if it’s not done well? We usually end up making assumptions and possibly building the wrong thing. Translation: delays on development, reduced productivity, and nobody wants that!

So teach us everything you know one step at a time, and we’ll make something great together.

Gaslight is a ten year old custom software development and UI/UX design consultancy in Cincinnati, OH. At ten years, you have to understand your competition and be true to your core values. There are plenty of companies out there that build software - some do it well and some don’t. There are equally plenty of consulting companies that give great advice and some… not so much. What makes Gaslight unique is that we have been very intentional about being the very best at both. At our core, we build world-class software that is flexible and scalable to adapt to the changes your business will undoubtedly go through. We have also assembled our technical teams that are eager to communicate and consult the client throughout the length of the project, and many times, beyond it. We want our team to have a strong connection to our clients to understand their goals and objectives.

At Gaslight we feel that we have so much to offer our clients. It starts with building a trusted relationship, and acting as advisors to build the software our clients deserve.

Often times, development companies claim to be consultancies, but in this business actions speak louder than words! Let me walk you through our process and give you some insight into the people you will be working with and the sessions we like to go through to deliver the most value to our clients. Before you know us, we have to get to know you. As the Sales Director here at Gaslight I am tasked with finding organizations that could benefit the most from working with Gaslight.

Here are some of the things I look for:

• Organizations in “Growth Mode”
• Companies that know they need to innovate, but aren’t sure how or where to start
• Organizations that have fallen behind competition in their space due to lack of technology innovations
• Companies in an industry that have narrow margins where we can give them a competitive advantage by building software that makes their business run more efficiently
• Companies that have an opportunity to give their users a better experience (UX)
• Companies who have a development team who “keeps the lights on” but need an outside team to come in and help them build new innovative functions and features
• Start-ups looking to build an industry disrupting product

Our clients want more than just cookie-cutter or built to spec software. Instead, we form authentic partnerships and work side by side to identify end-users’ needs and design and develop ambitious custom solutions.

• Our teams are created to maximize efficiency and communication.
• Every step together is transparent so that our clients are in the best position to make good decisions.
• We craft software that works better, lasts longer, and is easier to use, maintain and modify.
• We work to leave a lasting impact on the communities we engage with.

Our approach is tried and true… but we feel that to be successful we really need to be your strategic partner in growth. We know that project success is largely correlated to the relationship we build with our clients and our understanding of their business. We will only build things that we wholeheartedly believe will help you achieve your business goals & objectives.

Use Elixir protocols to bring polymorphism to your data structures

This is the second in a series of posts we are doing on refactoring patterns in Elixir, a series that stemmed from working through Martin Fowler’s book Refactoring. In the first part of this series, we looked at using pattern matching in function heads as a tool to use for refactoring complex conditionals.

Pattern matching is ubiquitous in Elixir and Erlang, and it is a great tool to use for cleaning up complex conditionals in most common cases. To recap what we did in the last post, let’s take a look at this code sample ported over to Elixir from the JavaScript example in Martin Fowler’s book, and then see how we were able to refactor it using pattern matching:

The Bird module before refactoring:

defmodule Bird do


  defstruct type: nil, number_of_coconuts: 0, voltage: 0


  def plumage(bird) do
    case bird.type do
      "EuropeanSwallow" ->
        "average"
      "AfricanSwallow" ->
        if bird.number_of_coconuts > 2 do
          "tired"
        else
          "average"
        end
      "NorwegianParrot" ->
        if bird.voltage > 100 do
          "scorched"
        else
          "beautiful"
        end
      _ ->
        "average"
    end
  end
end

The Bird module after refactoring:

defmodule Bird do
  defstruct type: nil, number_of_coconuts: 0, voltage: 0


  def plumage(%__MODULE__{type: "AfricanSwallow", number_of_coconuts: num}) when num > 2, do: "tired"


  def plumage(%__MODULE__{type: "NorwegianParrot", voltage: voltage}) when voltage > 100, do: "scorched"


  def plumage(%__MODULE__{type: "NorwegianParrot"}), do: "beautiful"


  def plumage(%__MODULE__{}), do: "average"
end

Just looking at the before and after versions of the above code snippet, we can see that pattern matching in function heads gives us a huge benefit and an easy win in the readability department. Our code is now easier to understand and reason about: with only four cases for the plumage/1 function, we can easily find and determine what will be returned from the function for a given Bird.

We did, however, note one caveat to the refactoring tool used above: assuming we had a larger variety of Birds to handle, with each variety requiring some unique logic to determine its plumage, we would naturally arrive at a situation where the shear amount of function heads that we would need to create would become overwhelming and lead to harder and harder to follow logic. Not only that, but since calls to these functions would fall through from top to bottom in the order they are declared, we would also have to think long and hard about what order to place the function heads in to arrive at the intended behavior. Eventually, we would reach a breaking point where maintaining this function would start to become intractable.

One solution for dealing this is actually quite simple: if we are dealing with a plethora of different kinds of Bird that all have different conditions that determine what their plumage is, then perhaps we should break away from the generic idea of a Bird and create data structures that are more specific and tailored to the kind of bird(s) we are actually working with. For example, given the code snippet above, maybe we want to have EuropeanSwallow, AfricanSwallow, and NorwegianParrot represented as data structures instead of just a Bird (or in addition to a Bird that would represent a general case).

Elixir actually gives us an elegant way of handling this kind of problem – protocols which you can read more about here. Essentially, a protocol allows us to declare one function and delegate out the implementation of that based on the type of the data passed in to the function. Keeping with our Bird example, we might have a protocol Bird.plumage/1 and delegate out specialized implementations of the function based on our EuropeanSwallow, AfricanSwallow, and NorwegianParrot data structures. Note that we can also have a fallback implementation for protocols so that we can handle generalized cases if that is what we need. Let’s take a look at what our protocol definition looks like:

defprotocol Bird do
  @fallback_to_any true
  def plumage(bird)
end

There are a couple things of note here. First, defining a protocol is more or less the same as defining a module (and, in fact, this will generate a module for us), and second, we define only function heads inside of the protocol without providing an implementation. The @fallback_to_any true declaration tells Elixir to reference an implementation of the function it marks for the Any data structure. We will look at an example of that below, but for now just note that you can use this to provide a generalized fallback implementation.

So once we have a protocol set up, how do we define our own custom implementations of the function(s) declared in the protocol? Let’s take a look at what our implementation would look like for the NorwegianParrot, and while we are at it, we will also create a module for NorwegianParrot and define a struct for it:

defmodule NorweiganParrot do
  defstruct voltage: 0


  defimpl Bird, for: NorweiganParrot do
    def plumage(%NorweiganParrot{voltage: voltage}) when voltage > 100,
      do: "scorched"


    def plumage(_), do: "beautiful"
  end
end

And for the EuropeanSwallow and AfricanSwallow, we would have something like:

defmodule EuropeanSwallow do
  defstruct number_of_coconuts: 0


  defimpl Bird, for: EuropeanSwallow do
    def plumage(%EuropeanSwallow{}), do: "average"
  end
end

and

defmodule AfricanSwallow do
  defstruct number_of_coconuts: 0


  defimpl Bird, for: AfricanSwallow do
    def plumage(%AfricanSwallow{number_of_coconuts: num}) when num > 2,
      do: "tired"


    def plumage(_), do: "average"
  end

We are defining the specialized implementation for the three types of bird we are concerned with here. To do this, we use defimpl #{ProtocolName}, for: #{MyDataType} to let Elixir know that this is the implementation of the Bird protocol for the type we are passing as the value to for:. Just like in normal Elixir modules, we can use pattern matching and guard clauses when declaring functions, and we can also have multiple function heads for the same declaration. This is all just good ole classic Elixir.

The great thing about this is it gives us a much more focused, granular level of control over the way a function behaves based on the type of data it receives. We no longer have to worry about how a NorwegianParrot‘s plumage is calculated when we are working on our implementation of the AfricanSwallow.

As I mentioned above, we can also define a fallback implementation that will catch any parameters that are passed to Bird.plumage/1 that don’t match the three specialized implementations we worked out above. You can do that by defining an implementation of the protocol for the Any data type like this:

defimpl Bird, for: Any do
  def plumage(_), do: "average"
end

With all of this in place, we can replace the initial code snippet from above with our protocol, giving us polymorphism on the parameters that get passed to Bird.plumage instead of relying on pattern matching in a single module and we can avoid potentially having to handle a large number of different cases in the same file. We now have more control over the behavior of the function and can write tests that can prove out different edge cases around the specialized implementations that we care about.

To finish this out, let’s look at what it might look like to call this code:

1> Bird.plumage(%AfricanSwallow{number_of_coconuts: 7}) ### "tired"
2> Bird.plumage("some general bird") ### "average"
3> Bird.plumage(%NorwegianParrot{voltage: 7000}) ### "scorched"

That wraps up our second installment in our Refactoring Elixir Series. I hope you enjoyed, and happy Elixiring to you!

I graduated high school and I never thought of being a developer. The term web developer wasn’t even a thing back then, people use to call them webmaster or web designers. I went to college for a while (nothing related to programing) then, after a year and a half I got a decent job and dropped out of school in order to work. The business closed down soon after, so I started a couple of businesses. Some were not successful at all and some were successful for a while but not life changing. I went on to working whatever job I could get in order to pay for my rent and the bills. I worked in retail, I washed dishes, I worked at factories, warehouses, pizza places, and everything in between. And every job I got I seemed to hate it more than the last one. The pizza places weren’t too bad but i was lucky to average $11/hr or $12/hr after tips.

After about 6 years working these types of jobs and many failed attempts to change my life for the better. I took things to another level and decided to learn to program. I tried learning while working full time but It just didn’t work out for me. I felt like every weekend I was learning the same stuff. That’s because I had already forgotten everything I learned the weekend before. Eventually I came to the realization that I was doing everything backwards. I realized was putting most of my effort into the wrong things, the low paying/anybody-can-do jobs. So I quit my main job at the time and got a different job where I only worked part time, on the weekends. That allowed me to put most of my effort, Monday through Friday, into my future, becoming a developer. I followed Brian Tracy’s 12 step method to accomplish any goal: I wrote down a new life schedule and a monthly budget that I followed religiously until I accomplished my first big goal. Getting my first job as a developer. Since I was only working on weekends, the money was more than tight. It was 700/month to be exact. But every single dollar was accounted for.

After about 7 months of quitting my job and only working weekends I was finally making progress as a developer. But, at that time, I did not have any mentors who I could ask for advice or help. So I did the obvious thing to do and I googled for suggestions on how to get mentors. That led to me attending every software developer related meetup in my city and cities nearby. That’s how I found Gaslight. They seemed to have the strongest javascript following on meetup.com in the area and I started attending their events. I remember how financially taxing attending their meetups was for me at the time. It was about 3 hours round trip plus paying for expensive downtown parking. Looking back, attending these Gaslight meetups turned out to be one of the best decisions I ever made in my life and that’s not an exaggeration at all. I learned about their apprenticeship program the first time i went, and eventually, I was told I was being considered for an apprenticeship program that coming up in about 3 to 6 month from the time I was told.

A few days later, I got an email from Chris Nelson (Gaslight apprenticeship manager), asking If I’d be interested to start sooner, the next Monday, due to someone else cancelling(I think, to be honest I didn’t care too much about the reason). Starting the apprenticeship at that time meant I had to move to a new city, get an apartment, etc. Even when the job wasn’t guaranteed. However, the answer was obviously yes. I drove down to Cincinnati and spoke to Chris about the all the details. I officially accepted the offer, and I acted cool and chilled until I left and got in the elevator and the doors closed. That’s when I finally got hysterical and started jumping. As corny as It may sound, I felt Chris Gardner(played by Will Smith) when he finally got the job in the last scene of the Pursuit of Happiness movie.

The apprenticeship put me in Kroger Digital and I had the opportunity to be part of 2 amazing teams during my time there. There was a lot of learning, mentoring, anxiety, imposter syndrome, work, fun, etc. All of which helped me become what I like to call, a “Real Developer” and Kroger ended up making me an offer and hiring me as a full time employee.

In summary, my life has not been the same since I started the Gaslight apprenticeship program, and again, that is not an exaggeration at all. Now days I work as a full time, full stack developer and help other self taught developers through my youtube channel: https://www.youtube.com/omarsuriel

Let me put this out into the world… I understand that my job at its core is to identify opportunities, connect a solution with our service and close the deal as soon as possible to drive revenue for my company, (wow, that seems a little cold when you actually put it on paper). In reality my day to day doesn’t seem that cold at Gaslight. On a daily basis I’m connecting with intelligent people, learning about their challenges, and helping them decide if we are the right fit to help them. So when I hear, “We aren’t servers, we are sales people,” it makes me think of the old school, 1990’s “Boiler Room” sales that they used to teach at the entry level, yuck.

The message that the executive was hoping to get across that board room was this; we need to persuade prospects that are uncomfortable moving forward with the project to close regardless of how comfortable they are. When a prospect is uncomfortable, they stall, and his solution to stalling - push harder. He’s hoping to remove time from the equation. In his eyes time is what gives the prospect the opportunity to find a good excuse to back out of a sale. In reality this is human nature. We as humans are pressured by imposed deadlines and find comfort in having time to review.

The better solution here (like most things in life) is to find a balance. Your sales team has to move opportunities through the pipeline and close them on a consistent basis. If you are using metrics to track your pipeline, you will see obvious areas where your opportunities are slowing, or fizzling out. As a sales person, this is an opportunity to self evaluate the sales process and discover what YOU are doing wrong, not what the prospect is doing wrong. There are many sales tactics and tools you can put in place with the prospect to help them stay on track, while still giving them the opportunity to step on the brakes if they are uncomfortable moving forward, my favorite tool is the “MAAP - Mutually Agreed Action Plan”. Here is a great high level overview of a MAAP and how/when to use it by Sales Hacker.

If you carve an opportunity down to its core and start to think about why it may be slowing down, oftentimes you’ll find a lack of trust. If there is a need, and your service or product solves that need, and there is a budget in place that reports back solid ROI numbers - then why would an opportunity stall? Lack of trust. The prospect doesn’t fully trust you and/or your company. They don’t trust the solution you have laid out for them, or the competency of the team that is going to be assigned to their project. Being in the custom software development space these are often six to seven figure decisions, and making big moves with big waves to follow doesn’t come easy for most people. In a lot of ways their job, career, and professional reputation depends on making the right decision. Understanding this weight and showing empathy towards their situation will allow you to meet the client where they stand. They aren’t looking for someone to push them, they want you to stand next to them arm and arm and walk down the path together. Making every step in unison, moving forward naturally. They want to know that you stand behind your solution, and won’t disappear if it isn’t well received. They want to know that you have their back, that this is a team effort and they won’t be stuck alone having to answer to their boss (everyone has one) as to why they chose your solution, or went with your company over others. I challenge you to walk down that path with your prospects, practice empathy, and understand that large financial decisions are uncomfortable.

Obviously, there’s a place in the world for servers, and for sales people. What’s not so obvious is that you cannot rush trust. Forcing trust only benefits you temporarily to close a deal, and prospects see right through that. If you understand that building trust doesn’t come packaged in a metrics driven model, and you are genuine in helping your prospects, trust will happen naturally. And trust will give your prospects the piece of mind to make a decision and move forward with the project. Help them understand that you are setting the pace, yet they are the ones running the marathon, completely in control of the end result.

I’m sure you are asking, “Ok Mr. know it all… How do I build trust and close deals quickly?” The answer is complex, but working for an organization that values doing right by their clients is the first step. “Getting Naked” by Patrick Lencioni is a required reading for all employees at Gaslight. Start there, and remember that doing right by the client, even if it means short-term financial sacrifice for you personally, will ALWAYS come back to you in future success!

My personal philosophy:

In sales you can frequently get bogged down by metrics and statistics, but at the end of the day all I really care about is constantly improving my ability to make my prospects and clients feel comfortable making complex decisions. Everything else will flow from that simple action.

So, you want to build and app? So does everyone and their uncle.

You aren’t the only one that feels you need an app to stay relevant in the market, but we believe it’s mistaken for table stakes. We’ve overwhelmed our users by asking them to download an app for every tiny task we want them to do. Ever heard of app-fatigue? Users struggle to see the value from their download, in fact, only 40 apps are used per month of 80 that are downloaded, according to annieapp.com. The average amount a company will spend on a custom app is about one million, that’s quite a bit for it to be deleted after they redeem their free gift. If you do want to spend that kind of money, it better be worth it!

Still want an app? Tell me why … do you simply think it’s cool? Do you think you users will enjoy it? Remember, an app only sticks when it provides continuous value to its user. (Hey, that’s one of our core values). Let’s think about what problem you are actually trying to solve, instead of launching an app that feels a lot like a bandaid over top of the struggle. If your ultimate plan to build an app has been interrupted by us, then we’ve done a good job. But we won’t leave you here with wide eyes, download our checklist to identify when an app makes sense. Maybe an app makes sense for you, maybe not. We challenge you to find a solution to fit the user’s problem, not make the problem fit your preferred solution.

People often compare the cost of an apprenticeship program to the cost of hiring an outside recruiter - but we have to be honest with you, that makes no sense! A traditional recruiter will charge a fee to find a developer, and even then, what is the criteria they use? Even if this fee is high (say $25,000), it’s often quite a bit less than the hourly cost for six months for a mentor and two apprentices. The problem with this comparison is that it does not account for the value delivered over those six months.

Our apprenticeship model is about providing you with a team that produces both short-term and long-term value. In fact, this team can start delivering on your project within the first few weeks.

Download our side by side comparison to see why the choice is obvious.

As I have been learning Elixir in the past few months, I have heard a lot about processes. Lots of Elixir’s biggest selling points, like its concurrency support, scalability, and fault tolerance, are possible because of the features and characteristics of processes.

Processing Processes

Elixir runs on the Erlang VM, and processes are a core part of Erlang’s architecture. Erlang’s concurrency model relies on the idea of Actors. An Actor is a self-contained process that performs a specific task and can only communicate with other processes via message-passing. Erlang’s processes are incredibly lightweight and fast, spinning up in MICROseconds. This small overhead also means you can have a lot of them at once, up to 268 million.

Elixir provides a lot of incredibly useful abstractions on top of Erlang’s processes, so you don’t usually need to interact with them directly, but I wanted to get in the weeds a little bit. So I made a very simple Elixir application that utilizes some of the basics of spawning processes and message-passing. The full source code for the project can be found here.

Math Racer

MathRacer is a very simple and useful competitive addition application. It’s public API is one function: MathRacer.race/1. It takes an integer and spins up that number of MathRacer.Adder processes, which then perform a complicated mathematical operation (1 + 2). The result and the time it took to complete are printed to the console for each Adder, and at the end, the overall average time to complete the operation is printed.

iex(9)> MathRacer.race(10)
It took 67 microseconds to get the result: 3
:ok
It took 67 microseconds to get the result: 3
It took 67 microseconds to get the result: 3
It took 67 microseconds to get the result: 3
It took 92 microseconds to get the result: 3
It took 97 microseconds to get the result: 3
It took 97 microseconds to get the result: 3
It took 97 microseconds to get the result: 3
It took 97 microseconds to get the result: 3
It took 97 microseconds to get the result: 3
The average time was 84.5 microseconds

Let’s start with the entry point of the application: MathRacer.race/1:

defmodule MathRacer do
  def race(num_of_adders) when is_integer(num_of_adders) do
    range = 1..num_of_adders


    coordinator_pid =
      spawn(MathRacer.Coordinator, :loop, [[], Enum.count(range)])


    range
    |> Enum.each(fn _ ->
      adder_pid = spawn(MathRacer.Adder, :loop, [])
      send(adder_pid, {coordinator_pid, {:add, [1,2]}, :erlang.timestamp()})
    end)
  end
end

Here we see two of the functions that Elixir gives you for dealing directly with processes: spawn/3 and send/2. spawn/3 is used to start a process. It takes a module, and atom representing a function in that module, and a list of arguments. It starts a process by calling the given function with list of arguments. The spawn function returns the PID (process identifier) of the process, which is placed into a variable for later use. Two kinds of processes are spawned in this function. One calls the loop/2 function of the MathRacer.Coordinator module with an empty list and the length of our range as arguments. The second calls the loop/0 function of the MathRace.Adder module with no arguments. We’ll look at what these functions do later.

The other important function used here is send/2. This is how messages are sent between processes. It is called with the PID of the process you are sending a message to, as well as the message itself.

Our race/1 function takes the number passed to it, spawns that many MathRacer.Adder processes and sends them each a message in the form of a tuple containing the PID of the coordinator process, another tuple contianing the atom :add and a list of two numbers, and a timestamp taken using a function from the core Erlang module.

Let’s take a look at the other side of this message sending equation. The core of our application is the MathRacer.Adder module.

defmodule MathRacer.Adder do
  def loop do
    receive do
      {sender_pid, {:add, [a, b]}, start_time} ->
        send(sender_pid, add(a, b, start_time))
      _ ->
        :error
    end
  end


  def add(a, b, start_time) when is_number(a) and is_number(b) do
    {:ok, a + b, :timer.now_diff(:erlang.timestamp(), start_time)}
  end
end

This module contains two functions: add/3 and loop/0. add/3 is a simple function that takes two numbers and a timestamp, and returns the sum of the two numbers and the difference between the time it receives and the time it executes. This utilizes the timer module from Erlang. The now_diff/2 function takes two Erlang timestamps and returns the difference in microseconds.

The loop/0 function is the interesting part. It contains a receive block. This is how an Elixir process defines the messages it can receive. Using pattern matching, you list the kinds of messages that your process can receive and give a default response for any unknown messages. The rest is simple. If you send MathRacer.Adder the message it expects, it responds by sending the PID given to it a message containing the result of the add/3 function call.

The last piece to look at is the Coordinator module.

defmodule MathRacer.Coordinator do
  def loop(results \\ [], results_expected) do
    receive do
      {:ok, sum, time} when is_number(sum) and is_number(time) ->
        IO.puts("It took #{time} microseconds to get the result: #{sum}")
        new_results = [time | results]
        if results_expected == Enum.count(new_results) do
          send self(), :exit
        end
        loop(new_results, results_expected)
      :exit ->
        average = Enum.sum(results) / Enum.count(results)
        IO.puts("The average time was #{average} microseconds")
      _ ->
        loop(results, results_expected)
    end
  end
end

This module just contains a loop/2 function. Inside, we can see some similarities to the loop/0 funcion in MathRacer.Adder, with a few more possible messages defined. loop/2‘s arguments are a list, which will be used to build up a list of all the results it receives, and a number representing how many results it should expect to receive. Notice that the loop/2 function is recursive. Two of the message options end by calling the loop function again. This is because the coordinator process has a different role than the adder processes. Each Adder process does its calculation and returns, then exits. If you need to add again, you need to spawn another process. The coordinator process, on the other hand, needs to hang around and wait for every adder’s result to come in. In order to accomplish this, it must call it self once it receives a message in order to keep listening for the next one.

When the Coordinator receives a message from an Adder, it first prints a message to the console informing you of the time it took that Adder to get its result. It then adds the new result to its ongoing list of results and checks to see if its waiting on any more. If it is, the loop function calls itself with the new list of results. If it has received all its expected messages, the coordinator process actually sends itself a message, consisting of the atom :exit. Processes can send themselves messages. This is useful for isolating unrelated logic instead of mixing concerns into the same function. When the Coordinator receives an exit message, it takes its list of results, calculates the average time, and prints that to the console and exits.

send(self(), :wrap_it_up)

So that’s a (not so) brief overview of some of the basics of dealing with processes in Elixir. There’s a lot more to look at. We haven’t covered linking or monitoring a process, which is how you can have things like Supervisors and other awesome Elixir functionality. But I hope this got you interested in digging more into how Elixir works under the hood and how it does the awesome things it does.

Label Page Components with Template Areas

Defining and rearranging template areas is one of the cleanest and straight-forward methods for creating template parts that can put together in different page layouts. Here is what a simple interchange grid would look like.

Define The Grid

First, we must define our grid lines. For this example, we will create three columns of equal width and three rows with a large center row.

body {
  display: grid;
  grid-template-columns: repeat(3, 1fr);
  grid-template-rows: 1fr minmax(300px, 65vh) 1fr;
}

Assign Your Template Areas

Once you have the grid lines set, we’ll create classes for the containers that will represent the different sections of our grid, and then assign each one a grid-area title.

.header {
  grid-area: header;
}
.main {
  grid-area: main;
}
.list__col-1 {
  grid-area: list-col-1;
}
.list__col-2 {
  grid-area: list-col-2;
}
.list__co3-1 {
  grid-area: list-col-3;
}
.sidebar {
  grid-area: sidebar;
}
.footer {
  grid-area: footer;
]

Defining The Layout

To define our base layout, we will be using the grid-template-area property. The names assigned to each container’s grid-area can be laid out according to the defined columns and rows. When we add each row of template areas to a new line, the css becomes a visual pattern of our grid layout.

body {
  grid-template-areas: 
    "header header header"
    "main main sidebar"
    "footer footer footer";
}

Adapt The Layout for Different Template Types

Now we can get creative by defining several layout variations for separate templates. For this example, we will create CSS for an article template with header or sidebar and an article list template.

body.template__article {
  grid-template-areas: 
    "main main main"
    "main main main"
    "footer footer footer";
}

body.template__list {
  grid-template-areas: 
    "header header header "
    "list-col-1 list-col-2 list-col-3"
    "footer footer footer";
}

Now that we can easily create different types of variety of defined layouts, we can now consider how is method will help solve another problem. With the rise of design systems, we are building consistent components that are pieced together to create larger components that fit together into pages. We’re no longer designing simple pages, so how do we incorporate this great page layout method into a design system process?

More on that another day…

Why Hooks?

Why should you use hooks? What benefits do they provide?
* They give you the ability to connect and reuse stateful logic, removing the need for render props and higher-order components. * They help take the logic that is spread out among the many lifecycle methods of a complex component and relocate it into smaller independent functions. * They reduce confusion on when or why you need a component to be a class versus a function.

useState at a Glance

The useState hook allows you to give state to a functional component - meaning you will no longer need to worry about making a class component if you want to have state in a functional component. Let’s look at a small example and explain what is going on.

import React, { useState } from "react";
import _ from "lodash";

export default function Tasks(props) {
  const [newTask, setNewTask] = useState();
  const [tasks, setTasks] = useState([]);

  function addTask() {
    setTasks([...tasks, newTask]);
    setNewTask("");
  }

  return (
    <div>
      <input
        type="text"
        value={newTask}
        onChange={e => setNewTask(e.target.value)}
      />
      <button onClick={addTask}>Add</button>
      <div>
        {_.map(tasks, task => (
          <div>{task}</div>
        ))}
      </div>
    </div>
  );
}

In this example we are making a task list. The user types in a task, clicks the Add button, and a task is added to the task list. So what is going on with the react hook useState?

• Every time useState() is called two things are returned. A new state variable and a function to update the state variable. As you can see const [newTask, setNewTask] = useState() creates a new state variable and using array deconstruction we call the new state variable newTask and the function to update this variable setNewTask
• You can give a state variable an initial value by passing in an argument to useState. On the following line we give the state variable tasks an initial value of an empty array, const [tasks, setTasks] = useState([]). Here it is an array but it can be anything, a string, integer, or an object.
• To use or display the state variables all you need to do is call the state variables tasks or newTask directly.
• To update a state variable let’s look at the addTask() function. Inside this function you can see we are updating both the tasks state variable and newTasks state variable. In both examples you can see we just pass in a new value to the update function and react will re-render the component with the new value. One thing to point out is you will want to follow the same rules you always have of not mutating the state variable directly but recreating it and adding to it. As you can see in setTasks([...tasks, newTask]) we create a new array by deconstructing the tasks state variable and append the newTask state variable to the end.

useEffect at a Glance

The useEffect hook combines several of the most commonly used lifecycle hooks (componentDidMount, componentDidUpdate, and componentWillUnmount) used in classes into one central API. Now let’s add on to the previous example a useEffect hook:

import React, { useState, useEffect } from "react";
import _ from "lodash";
import axios from "axios";

export default function Tasks(props) {
  const [newTask, setNewTask] = useState();
  const [tasks, setTasks] = useState([]);

  useEffect(() => {
    axios({
      method: "get",
      url: "https://api.jsonbin.io/b/5c6af0c09dfbb91d718215d8",
      params: {}
    }).then(response => {
      setTasks(response.data.tasks);
    });

    /*return function cleanup() {
      //put cleanup logic here
    }*/
  }, []);

  ...

}

This uses the axios package to asynchronously fetch tasks and then set the state variable tasks to the returned list of tasks. So what should you be looking at in the useEffect hook?

• The first thing to notice is that useEffect is called inside of the component. This gives it access to everything that is declared in the component including the state variables created by the useState hook or any other variables generated from hooks such as useReducer or useContext. To be clear, you will not have the ability to call any of these hooks directly in useEffect. For example you can’t do const [var, func] = useState() inside of the useEffect hook. You can only call hooks directly inside the function component.
• useEffect takes two arguments: a function and an array.
• The function is what will be called when the useEffect hook is called. Here we are calling out to an API endpoint to retrieve a list of tasks. As you see commented out you can return a function to perform cleanup logic. This is great if for example you are dealing with pub/sub connections and you need to clean up those connections.
• The second is an optional parameter which is an array. This tells the useEffect hook when it should be called. If nothing is passed in here the useEffect hook will be called on every render. Passing in an empty array will only run this hook on mount and unmount. Passing in an array with the state variable, for example tasks, will call the hook every time it is updated.
  
• You can have as many useEffect hooks in a component as needed. Ideally you should create one for each set of related pieces of logic that you need. For example I would create a new useEffect in the scenario were I wanted to update the API endpoint every time tasks is updated.

Conclusion

React has done a lot through the years to improve itself. I hope this gives you some insight into how to use hooks and the value they bring. I personally feel on top of the benefits previously mentioned, this will help in making code easier to read but also the logic of a component and its lifecycles easier to follow.

Ever come across a site that is laid out beautifully across all screen sizes? It responds as you narrow or widen your window, the sidebar wraps effortlessly as real estate becomes sparse, the gutter spacing between elements is consistent; it’s glorious. But then you start to scroll. There’s weird white space between the header and main content, the footer feels like it’s falling off the page, content starts to run together and hierarchy is lost. That’s what I’m talking about. It is so easy to create and maintain these horizontal grids, but the structure is lost as you move down the page — but it doesn’t have to be!

I’ve long envied the blog post that showcases a site falling effortlessly into a vertical grid. It’s always been this thing that I aspired to do, so I decided to finally demystify it. And, thankfully, it’s really not too complicated.

Establishing the grid

First things first, we have to decide on and set up the vertical rhythm on the page. So, where to begin? What is a vertical unit we already have in our arsenal? Line height. Every site has content; all content has a line-height—Let’s go with that!

Let’s assume our site has a base font-size: 20px; and a line-height: 30px;

html, body {

font-size: 20px;

    line-height: 30px;

}

If our base line-height is 30px, then we should run with a 30px vertical grid. But what does that mean? That means that we need to use 30px as a base unit for spacing throughout the site; everything should be in multiples of 30px. And voilà — we’ve got a vertical grid.

Want some space between those consecutive .form elements?

.form + .form {

margin-top: 90px;

}

Need some breathing room inside that .sidenav?

.sidenav {

padding: 30px;

}

Your <h1> not fit inside those 30px?

h1 {

font-size: 50px;

line-height: 60px;

}

Where is gets tricky

Great! It’s that simple: set a base line-height, then just use multiples of it for everything in your system. But there are some snags we need to address before this can work entirely.

Browsers like to add in their own default declarations.

We need to strip the browser of its default spacing. This means the sizing, padding and margins on the body, h-tags, lists, links, etc. so that we’re starting from the ground up. We want to strip everything away so that we can build it back up again onto our grid. So, in our base styles, let’s add

html, body {

margin: 0;

padding: 0;

}




* {

line-height: 30px;

}




h1, h2, h3, h4, h5, h6, ol, ul, blockquote, p {

margin: 0;

}

Scalability & Maintainability

Cool, cool, cool. That’s great and all, but what if I want to change my grid after I’ve spent some time with it? Sass to the rescue!

To set up a more maintainable and responsive vertical grid, we’ll want to use the power of Sass variables and functions to our advantage. Thankfully, it’s not too complicated. We just need three variables and one function and we’re off to the races.

Variables

$font-size-base: 20px;

$line-height-base: 1.5;

$grid: $font-size-base * $line-height-base;

Function

@function grid($count) {

  @return calc(#{$grid} * #{$count});

}

Where $count is the multiple of grid lines we want to use. So, calling grid(1) would return 30px, grid(2) would return 60px, etc. This allows us to declare grid lines without hard-coding any values.

So, our grid setup would look something like

html, body {

font-size: $font-size-base;

line-height: $grid(1);

}




* {

line-height: grid(1);

}

And using the grid would look something like

.form + .form {

margin-top: grid(3);

}




.sidenav {

line-height: grid(1);

padding: grid(1);

}




h1 {

font-size: 2.5em;

line-height: grid(2);

}

Aaand we’re done!

Tada! That’s how you set up and maintain a vertical grid. It’s just a few lines of code and a lifetime of happiness. Okay, maybe that’s an overstatement, but I love when I learn that something seemingly complicated is actually really simple. It’s a beautiful, beautiful thing.

Want to try if for yourself? Play with this Codepen!

Initially, we just want to get to know you - your motivations, the things that make your shoulders raise with a quick breath of excitement. We’ll ask how we can help you accomplish your professional and personal goals. We aim to make you comfortable to sit back and talk about things outside of the project. This allows us to grab a better understanding of the person you are, and envision the team that would align with your personality. If the feeling is mutual, we’ll move on to the three phases of scoping work.

Business scoping tells us about your organization. What makes you unique, what you identify as a challenge, who your competitors are, and areas for improvement. Brag about your vision, your 1, 5 and 10 year plan for the business. Flaunt your people, the culture, and the story of how you got to where you are today. We want to understand your roles & responsibilities, who supports who, the reporting structure, and how can we make you even more of a crowd favorite in your marketplace.

Technical scoping - now the ball is rolling and we’re all kinds of excited. This is where sales takes a step back and let the pros do the talking. We’ll bring in a technical resource from our team during this stage who embodies confidence and complexity in that space. Empathy & Story Mapping wraps up this phase. The goal with this exercise is to understand how to make your idea come to life through technology - and oftentimes, this is the most challenging step. We are never going to tell you that building custom software is easy, but we will assure you that it’s worth it.

And as you’ve been ramping up ideas and anxiously waiting at the same time, project scoping brings us home. But here is where we are different - we’ll build the scope of work with you in the room and that provides financial clarity. It may be a first draft, but we want you to tell us what we should be building. It’s important to be open about pricing and aligned on goals and timelines.

A traditional Gaslight project typically lasts for six to eight months and costs anywhere from 300,000 to 500,000 dollars. But we welcome non-traditional just as often. If we communicate effectively throughout the process the final step is more of a formality. This final step brings us to some signatures and we roll right into kick off meeting plans, we’re off to the races. Let’s build something amazing, and let’s build it together!

To learn more about what we’re capable of … visit our services page or set some time for coffee with us.

Replace Complex Conditionals in Function Bodies with Pattern Matching in Function Heads

Several of us developers at Gaslight have been meeting up on Fridays to discuss Martin Fowler’s seminal book, Refactoring. The 2nd edition of his book, which is what we have been focused on, features examples written in JavaScript. The 1st edition, released in 2000, contained examples in Java.

The first day we got together to discuss the book, an interesting question was raised: How do language paradigms and specific language implementations affect the way developers tackle the task of refactoring? For example, in cases where you might reach for a tool like inheritance in object-oriented languages, what would your alternative be if you were working in a functional language like Elixir or Erlang where tools such as inheritance are unavailable? On the flip side, if you were going to reach for a tool like pattern matching in Elixir, what would you reach for if you were coding in, say, Ruby?

Since many of us here at Gaslight share a passion for Elixir, we started discussing if there was a set of “refactoring patterns” that we find ourselves coming back to when working on Elixir projects. It soon became obvious that there are plenty of techniques when it comes to refactoring Elixir, and we thought it would be great to put some of those down in writing and share them with the community.

Now, without any further ado, let’s jump into our first refactoring pattern in Elixir:

Replace Conditional with Function Head Pattern Matching

Our first pattern is a spin on one of the more influential refactoring techniques Martin Fowler brings up in his book: “Replace Conditional with Polymorphism”. While this pattern does not, perhaps, fulfill what we might traditionally think of as polymorphism, it is a great option for refactoring complex conditionals in function bodies. We will also share another approach to refactoring conditionals using Elixir protocols – an approach that gives you polymorphism on data structures – in a future post.

To demonstrate how this pattern looks, let’s take a look at an example from Refactoring ported over to Elixir:

defmodule Bird do

  defstruct type: nil, number_of_coconuts: 0, voltage: 0

  def plumage(bird) do
    case bird.type do
      "EuropeanSwallow" ->
        "average"
      "AfricanSwallow" ->
        if bird.number_of_coconuts > 2 do
          "tired"
        else
          "average"
        end
      "NorwegianParrot" ->
        if bird.voltage > 100 do
          "scorched"
        else
          "beautiful"
        end
      _ ->
        "average"
    end
  end
end

The example here is pretty straightforward: we pass in a Bird struct to the plumage/1 function and pattern match on the type of bird in a case statement. Given the size of this function and its simplicity, it does not immediately jump out as being in dire need of refactoring, but there are a few “smells” that stick out if you have been working with Elixir for a while:

1. We are pattern matching on strings in the case statement. If new requirements come in that would force us to add more clauses to this case statement, this approach can get unwieldy in no time.
2. We are using nested if blocks inside of matches in our case statement.
3. In the case of the EuropeanSwallow and the AfricanSwallow with less than 2 coconuts, we can just fall back to the default value of average. This would allow us to remove the “EuropeanSwallow” clause from the statement altogether, but we would still need to address the extra conditional for the AfricanSwallow.

So what are some solutions to clean this up a bit and make it easier to work with? Let’s extract the case statement conditional to pattern matching in function heads:

defmodule Bird do
  defstruct type: nil, number_of_coconuts: 0, voltage: 0

  def plumage(%__MODULE__{type: "AfricanSwallow", number_of_coconuts: num}) when num > 2, do: "tired"

  def plumage(%__MODULE__{type: "NorwegianParrot", voltage: voltage}) when voltage > 100, do: "scorched"

  def plumage(%__MODULE__{type: "NorwegianParrot"}), do: "beautiful"

  def plumage(%__MODULE__{}), do: "average"
end

Since Elixir and Erlang let you define multiple function heads for functions with the same arity, we can rely on pattern matching on our arguments and move more specific, conditional cases towards the top, leaving default and generic cases as the last definition(s) for a given function head.

The use of guard statements in the function heads allows us to remove the two nested if blocks from the original case statement: we extract the data needed to determine whether or not a condition has been met using pattern matching while ignoring data that is irrelevant for our calculation. For instance, we only need to know how many coconuts the AfricanSwallow has to determine whether it’s plumage is tired or average, so we can ignore the voltage property altogether.

The combination of pattern matching in our function heads along with guard clauses allows us to capture any Bird that doesn’t match our conditional logic or any of our top function heads with a default case: def plumage(%__MODULE__{}), do: "average".

When Should We Use Replace Conditional with Function Head Pattern Matching?

This pattern is a great approach for cleaning up if/else blocks and nested conditionals inside of function bodies. It also works well if all you are doing inside of a function body is running a case statement on a single property of a data structure, as is the case in our example above.

What Are Some Gotchas With This Pattern?

Elixir’s pattern matching is a super powerful tool that gets used a lot, and rightfully so. It can make your code more declarative and easier to reason about, but you certainly can get too carried away with it, and many Elixir/Erlang developers have probably been bitten by overuse of pattern matching before.

To illustrate this point, imagine based on the example given above that we had a requirement to calculate a wide variety of plumages for every single species of bird in existence on the planet! Further complicating things, each species of bird has different attributes that determine their plumage. If you attempted to codify that using pattern matching in function heads in your Bird module, you would be in the fastlane on a one-way street to “What even in the world is going on here?!”

Granted, the example I just gave is an argument ad absurdum, but I find that there is generally an upper limit on how many function heads you can match on before your code actually starts becoming more difficult to read and understand. While I can’t provide any specific advice on what that upper limit might be, I generally use this as a simple rule of thumb: If all of the function heads we are concerned with fit on the screen all at once, then our approach to pattern matching should work fine and the code will be easy to reason about. As we add more and more function heads, it becomes increasingly harder to reason about the code and thus less and less effective. In cases where this approach becomes unwieldy, you might want to try breaking out different data structures and having a protocol that has implementations for all of the data structures you need.

We will have a post coming up in the future that does just that: Replace Conditional with Polymorphism: Elixir Protocols.

Thank you for reading and happy refactoring!

Poor UX has Consequences

Identifying what is wrong or missing in an application can be challenging. And if you’re not intentional about your user’s experiences, then the UX might be costing you more than you realize. It can affect your goal conversions and user efficiency. You know…stuff that affects the purpose of having a website or application in the first place.

So maybe you are not able or not ready to bring a designer onto your project. Here are three problems to be aware of, and could indicate you have several more ..

Usability Problems to look for:

Visual Hierarchy

My former art director would always quote Incredibles, “When everybody is super, no one is!” This also applies to the content and components in your application. There is nothing more deadly to a layout than the poor visual hierarchy. Users will not know what to look at, no clear path to navigate the content, and the calls to action will be drowned out by everything else.

Signs of poor visual hierarchy:

• Do your tags clearly scale down in size, color, and weight?
• Is there very little white/negative space? Do your page elements butt up against the edges of the page and/or next to each other?
• Can you not tell what elements are clickable?
• Can you not tell what content is the most important?
• Can you not find the navigation in under 5 seconds?

Inconsistency

This is usually an easy problem to recognize. Elements or components that share the same functionality, but look or act completely different only confuse your user. I know this sounds crazy, but when a user sees an element that looks different from other elements, they inherently expect it to act differently. A simple design inventory of a type of component, like a button, will quickly reveal how consistent your application is. If they vary in color, size, shape, and in how they interact, then you have a usability problem.

Signs of inconsistency:

• Compare elements that do the same thing. Do they not look and act the same way?
• Do your animations not have the same timing and feel?
• Do you use different copy to direct the user to the same action?

Accessibility

Accessibility is such an important part of what we do. It is so often overlooked because we typically browse our own application the same way every day. Unless you personally know every possible user of your application, chances are you have of users with different needs.

Signs of poor accessibility:

• Do you not have alt tags on all your images?
• Use a color blind app to view you app, like Chromatic Vision Simulator. Do any of the colors blend together?
• Does your content not make sense when using a screen reader on your page?

Can you guess the next step?

There are many more issues that can arise from the lack of attention to design details on a project. If you found one of the problems above, chances are there are a few more. I think you know what I am going to say next. These problems are fixable with the help of a trained designer. And we may know a company with a few experienced designers who can help you out…

Multi-factor authentication relies on the user having two or more pieces of evidence (or factors) in order to gain access into a system. In this example we will implement a two-factor authentication system that requires the user to present two forms of evidence: what the user and only that user knows, their password, and a one time password sent to what only the user has access to, their email.

A Disclaimer

Now I’m just going to assume that if you’re reading this you’ve already got the first factor of two-factor authentication figured out on your own. If that’s not the case you can take a dive into the source code of the example application that already implements basic user authentication with Guardian and comeonin.

And if you figure out a better way of doing this (there’s always a better way), then please feel free to email me your suggestions, insults, or compliments.

Oh, and app dependencies

Here’s the list of dependencies I’m using. You can just throw this in your mix.exs file.

defp deps do
  [
    {:bamboo, "~> 1.0"},
    {:guardian, "~> 1.1"},
    {:pot, "~> 0.9.6"}
  ]
end

HMAC one time password generation

To generate this one time password, we will be using an Erlang library called pot. The function we will be using generates an HOTP, a one time password based on HMAC (hash-based message authentication code).

# the secret token we'll need to generate the hotp
# this will need to stay hidden from the user
token =
  :crypto.strong_rand_bytes
  |> Base.encode32()

# the one_time_pass we'll send to our user's email
one_time_pass = :pot.hotp(token, _number_of_trials = 1)

This code is going to come in handy later, so we’ll want to hold on to it. We’re creating a token with the :crypto application which is a module that provides access to cryptographic functions in Erlang. Then we’re using that token to generate a one time password that can only be used… You, guessed it: once.

Add a flag to the User? Add a flag to the User.

To get things poppin’ off we’re going to want to add a boolean flag to our User schema module and :users tabel. We can do that by generating a new Ecto migration.

mix ecto.gen.migration add_has_2fa_to_users

Then we’ll add the stuff to the other stuff…

### whatevertimestamp_add_has_2fa_to_users.exs ###

def change do
  alter table(:users) do
    add(:has_2fa, :boolean, default: true)
  end
end


### user.ex ###

schema "users" do
  field(:email, :string)
  field(:has_2fa, :boolean, default: false) # <- the new stuff
  field(:password_hash, :string)
  field(:password, :string, virtual: true)
end

Then we’ll run our new, fancy migration.

mix ecto.migrate

And to great success we now have :has_2fa attached to our users! This flag is going to tell us which users to send a one time password to and which ones to just let slide through with only one piece of authentic evidence. (Note: two factor authentication won’t protect anything if your passwords for both the system and your email are just password)

We’re gonna need some new routes

We need a place to go to render our form for 2fa, and when we’re there, we need a way for our user to send their one time password to the controller for examination and verification.

### lib/two_factor_auth_web/router.ex ###

get("/sessions/new/two_factor_auth", TwoFactorAuthController, :new)
post("/sessions/new/two_factor_auth", TwoFactorAuthController, :create)

And the corresponding form:

### lib/two_factor_auth_web/templates/two_factor_auth/two_factor_auth.html.eex ###

<%= form_for @conn, two_factor_auth_path(@conn, :create), fn f -> %>
  <label>
    Code: <%= text_input f, :one_time_pass, class: "qa-one_time_pass" %>
  </label>

  <%= submit "Submit", class: "qa-submit" %>
<% end %>

And now the all-powerfull controllers

Before we can get to the meat and potatoes of two-factor authentication, we need to take a gander at our session controller and, using that shiny, new boolean on our users, make sure we’re sending people to their appropriate destinations.

defmodule TwoFactorAuthWeb.SessionController do
  use TwoFactorAuthWeb, :controller
  import Plug.Conn

  alias TwoFactorAuth.Guardian
  alias TwoFactorAuth.Accounts
  alias TwoFactorAuthWeb.Mailer

  def new(conn, _), do: render(conn, "new.html")

  def create(conn, session_params) do
    # You could use a nested case here, but withs are cool, too
    with {:ok, user} <- Accounts.verify_login(session_params) do
      case user.has_2fa do
        true ->
          # remember that code at the beginning... this is where it went
          {token, one_time_pass} = Accounts.generate_one_time_pass(user)
          Mailer.deliver_2fa_email(user, one_time_pass)

          conn
          |> put_session("user_secret", %{"token" => token, "user_id" => user_id})
          |> put_flash(:info, "A heckin' 2fa code has been sent to you! Isn't that cool?")
          |> put_status(302)
          |> redirect(to: two_factor_auth_path(conn, :new))

        false ->
          conn
          |> Guardian.Plug.sign_in(user)
          |> put_flash(:info, "Login successful! But you should enable two-factor auth ngl")
          |> put_status(302)
          |> redirect(to: page_path(conn, :index))
      end
    else
      {:error, _} ->
        conn
        |> put_flash(:error, "You entered an invalid password or email!")
        |> put_status(401)
        |> render("new.html")
  end
end

Here we verify the the email and password passed in through session_params and return {:ok, user}. If the user has enabled two-factor auth on their account, we will generate them a one time password and email it to them. The user will fail the second factor of the authentication process if they don’t have access to their email or this one time password.

defmodule TwoFactorAuthWeb.TwoFactorAuthController do
  use TwoFactorAuthWeb, :controller
  import Plug.Conn

  alias TwoFactorAuth.Guardian
  alias TwoFactorAuth.Accounts

  def new(conn, _) do
    # we want to see if our token is empty, and if it is we redirect them back to the new session page
    # the goal here is to make sure we have the same conn that went through the session controller
    with %{} <- Auth.fetch_secret_from_session(conn) do
      conn
      |> render("two_factor_auth.html", action: tw        # just in case?
191
o_factor_auth_path(conn, :create))
    else
    _ ->
      conn
      |> put_flash(:error, "Page not found")
      |> put_status(404)
      |> redirect(to: session_path(conn, :new))
    end
  end

  def create(conn, %{"one_time_pass" => one_time_pass}) do
    # to verify the one_time_pass that comes in through the form we need the secret token off the conn
    # we also need the user_id to know who we're building the session for
    %{"token" => token, "user_id" => user_id} = get_session(conn)
    user = Accounts.get_user!(user_id)

    case Accounts.valid_one_time_pass?(one_time_pass, token) do
      true ->
        conn
        # our one time password can only be used... once
        # but we wanna go that extra mile and also invalidate it... just in case
        |> delete_session("user_secret")
        |> Guardian.Plug.sign_in(user)
        |> put_flash(:info, "Login successful!")
        |> put_status(302)
        |> redirect(to: page_path(conn, :index))

      false ->
        conn
        |> put_flash(:error, "The authentication code you entered was invalid!")
        |> put_status(401)
        |> render("two_factor_auth.html", action: two_factor_auth_path(conn, :create))
    end
  end
end

The legend of Plug.Conn

There’s a couple of challenges when it comes to dealing with the second factor of our authentication workflow. We need to be able to assure that there is one continuous session throughout the entire process, meaning that we can’t take any requests from a user that hasn’t first logged in with their username and password. We also need to be sure no sensitive data, i.e. our secret token, is being leaked to the user.

That’s where :plug_session comes in. This is the session store in conn[:private] that get’s encrypted when it’s sent to the client and is stored by your browser as a cookie. We’ll need to use put_session/3 and get_session/2 from Plug.Conn to assign and fetch our "user_secret" to and from the session.

### from Plug.Conn (conn.ex) ###

def put_session(conn, key, value) when is_atom(key) or is_binary(key) do
put_session(conn, &Map.put(&1, session_key(key), value))
end

defp put_session(conn, fun) do
private =
conn.private
|> Map.put(:plug_session, fun.(get_session(conn)))
|> Map.put_new(:plug_session_info, :write)

%{conn | private: private}
end

put_session takes your connection, the new key, and the value you want to assign to that key and puts them in :plug_session which lives in the private store of you connection.

conn[:private] is meant to be used by libraries and frameworks, such as Plug.Conn, to avoid writing to the user storage (the :assigns field).

So inside of our conn lives a special :private map that keeps our deep, dark secrets away from the user instead of leaking this information through conn[:assigns]. It’s meant to be used by libraries, such as Plug.Conn, to avoid writing to :assigns. Take a gander:

%Plug.Conn{
  private: %{
    :phoenix_action => :new,
    :phoenix_controller => TwoFactorAuthWeb.TwoFactorAuthController,
    :phoenix_endpoint => TwoFactorAuthWeb.Endpoint,
    :phoenix_flash => %{
      "info" => "A two-factor authentication code has been sent to your email!"
    },
    :phoenix_format => "html",
    :phoenix_layout => {TwoFactorAuthWeb.LayoutView, :app},
    :phoenix_pipelines => [:browser],
    :phoenix_router => TwoFactorAuthWeb.Router,
    :phoenix_view => TwoFactorAuthWeb.TwoFactorAuthView,
    :plug_session => %{
      "_csrf_token" => "MXbH2CPKOEs5iMltrA38ZQ==",
      "guardian_default_token" => "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJ0d29fZmFjdG9yX2F1dGgiLCJleHAiOjE1NTExMzE1NDMsImlhdCI6MTU0ODcxMjM0MywiaXNzIjoidHdvX2ZhY3Rvcl9hdXRoIiwianRpIjoiYmMyMzUyZDktODk1Yi00N2ZiLTkzMWItNWNlY2I2OTcwMjMzIiwibmJmIjoxNTQ4NzEyMzQyLCJzdWIiOiIxIiwidHlwIjoiYWNjZXNzIn0.5rFnDhFhB28LxksKqt_sc0ZfgYv-QbuTX5PLFKJkgi7J4NzxKt5N-PphQT2Z39uMWbp3V2p22Fz1Yz3pqisfWw",
      "phoenix_flash" => %{
        "info" => "A two-factor authentication code has been sent to your email!"
      }
    }
  }
}

Here we’re putting on the secret sauce during the first step of authentication and then sending the user along to the next stop:

### lib/two_factor_auth_web/controllers/session_controller.ex ###

conn
|> put_session("user_secret", %{"token" => token, "user_id" => user_id})
|> put_flash(:info, "A heckin' 2fa code has been sent to you! Isn't that cool?")
|> put_status(302)
|> redirect(to: two_factor_auth_path(conn, @new))

Take a look at this! Our "user_secret" is now nested comfortable in :plug_session:

%Plug.Conn{
  private: %{
    :plug_session => %{
      "_csrf_token" => "MXbH2CPKOEs5iMltrA38ZQ==",
      "guardian_default_token" => "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJ0d29fZmFjdG9yX2F1dGgiLCJleHAiOjE1NTExMzE1NDMsImlhdCI6MTU0ODcxMjM0MywiaXNzIjoidHdvX2ZhY3Rvcl9hdXRoIiwianRpIjoiYmMyMzUyZDktODk1Yi00N2ZiLTkzMWItNWNlY2I2OTcwMjMzIiwibmJmIjoxNTQ4NzEyMzQyLCJzdWIiOiIxIiwidHlwIjoiYWNjZXNzIn0.5rFnDhFhB28LxksKqt_sc0ZfgYv-QbuTX5PLFKJkgi7J4NzxKt5N-PphQT2Z39uMWbp3V2p22Fz1Yz3pqisfWw",
      "phoenix_flash" => %{
        "info" => "A two-factor authentication code has been sent to your email!"
      },
      "user_secret" => %{"token" => "some_token", "user_id" => 1}
    }
  }
}

When get’s redirected to our new path, that’s when we’ll implement get_session/2 to fetch our secret and check to see if we can even let them in and if we can, authenticate their one time password.

### from Plug.Conn (conn.ex) ###

def get_session(conn, key) when is_atom(key) or is_binary(key) do
  conn |> get_session |> Map.get(session_key(key))
end

defp get_session(%Conn{private: private}) do
  if session = Map.get(private, :plug_session) do
    session
  else
    raise ArgumentError, "session not fetched, call fetch_session/2"
  end
end

defp session_key(binary) when is_binary(binary), do: binary
defp session_key(atom) when is_atom(atom), do: Atom.to_string(atom)

After we retrieve our "user_secret", we want to drop it from the session. Our one time password can only be used… well once. But, for an added measure of security we want to make sure that token doesn’t exist anymore. This is where delete_session/2 comes in, which works like a specialized version of Map.delete/2, but for the :private stuff on our conn.

def delete_session(conn, key) when is_atom(key) or is_binary(key) do
  put_session(conn, &Map.delete(&1, session_key(key)))
end

defp put_session(conn, fun) do
private =
conn.private
|> Map.put(:plug_session, fun.(get_session(conn)))
|> Map.put_new(:plug_session_info, :write)

%{conn | private: private}
end

So now we have all the ingredients, assuming that the user has access to their email, for two successful pieces of evidence to finally sign them in to the system. That’s where the create path from the TwoFactorAuthController comes in:

def create(conn, %{"one_time_pass" => one_time_pass}) do
  # to verify the one_time_pass we need the token off of the conn, which lives in the :private map
  # (specifically under :plug_session)
  # we also need the user_id to know who we're signing in
  %{"token" => token, "user_id" => user_id} = get_session(conn, "user_secret")
  user = Accounts.get_user!(user_id)

  case Accounts.valid_one_time_pass?(one_time_pass, token) do
    true ->
      conn
      |> delete_session("user_secret")
      |> Guardian.Plug.sign_in(user)
      |> put_flash(:info, "Login successful!")
      |> put_status(302)
      |> redirect(to: page_path(conn, :index))

    false ->
      conn
      |> put_flash(:error, "The authentication code you entered was invalid!")
      |> put_status(401)
      |> render("two_factor_auth.html", action: two_factor_auth_path(conn, :create))
  end
end

The cherry on top

So what if our user doesn’t recieve the email? Maybe some shark was nibbling on some transatlantic communications cable and something went wrong? Well, we could give our user the option to resend their email. We’d just need a new route and some extra goodies in the controller to generate another one time password and token.

### liv/two_factor_auth_web/router.ex ###

post("/sessions/new/two_factor_auth/resend_email", TwoFactorAuthController, :resend_email)

### lib/two_factor_auth_web/controllers/two_factor_auth_controller.ex ###

def resend_email(conn, _) do
  %{"token" => _old_token, "user_id" => user_id} = get_session(conn, "user_secret")
  user = Accounts.get_user!(user_id)

  {new_token, one_time_pass} = Acconts.generate_one_time_pass()
  Mailer.deliver_2fa_email(user, one_time_pass)

  conn
  |> put_session("user_secret", %{"token" => new_token, "user_id" => user_id})
  |> put_flash(:info, "A new two-factor authentication code was sent to your email!")
  |> put_status(200)
  |> render("two_factor_auth.html", action: two_factor_auth_path(conn, :create))
end

So long

As more and more services are moving away from email-based two-factor auth, is this solution useful? Sure it is! We (I) learned a lot by doing this. Mainly, I learned to read all the way through the docs when reading about a particular module *cough* Plug.Conn *cough*. Am I going to remember this lesson learned? Probably not. But that’s besides the point. The information I’ve presented to you, the wonderful reader, could come in handy with loads of other stuff.

Next time you’re trying to pass weird and not-so-secure things from controller to controller, think back on this and ask yourself: is there a better way? Probably.