Adam Albrecht

Home Cooked Apps

2025-02-21T00:00:00+00:00

This article really spoke to me. I end up not building things all the time because I’m worried about product market fit, which tools to use to scale, etc. Instead, I need to lean into scratching my own itch and let it evolve however it may. Worst case scenario, I’ll build something useful for one person.

The author’s favorite family communication app shut down, so he built his own.

It launched in the first week of January 2020, and almost immediately, it was downloaded by four people in three different time zones. In the years since, it has remained steady at four daily active users, with zero churn: a resounding success, exceeding every one of its creator’s expectations.

Click Publish

2025-02-20T00:00:00+00:00

I’ve let this website atrophy a bit. Well, more than a bit. We’re coming up on 5 years since the last post - about as long as my oldest child has been alive and as long as I’ve been at my current job.

Not to imply that parenting and work have kept me so busy that I couldn’t write one measly blog post. But since that time, I’ve found myself less interested in writing the programming how-to’s that made up most of my past articles.

Still, I do want to write and share. I want this little corner of the internet to be a reflection of me.

But I’ve been dragging my feet, unsure of where I want to take it. My ~/Code folder contains several half-hearted rewrites of the website itself, proof that I’ll do almost anything to avoid writing a handful of sentences.

So today, I’m breaking the seal and clicking publish.

Add a Little Safety to your Elixir Structs with TypedStruct

2020-04-06T00:00:00+00:00

I’m working on an Elixir app at the moment and really enjoying it, but some of my recent dabbling in the type-safe worlds of Elm and Crystal have left me desiring a bit more structure in my code. The app I’m building involves a multi-step data transformation and so I have a data structure to properly represent this process. But since Elixir is a dynamically typed language, you can’t, for example, have a non-nillable field in a struct. The Elixir/Erlang ecosystem does, however, have a type-checking syntax called Type Specs, along with a tool, Dialyzer, that will find a fair number of errors at compile-time.

But I found that using defstruct with type specs to be fairly verbose and unintuitive. For example, let’s say you want a “Person” struct with the following attributes:

Name - string (non-nillable)
Age - positive integer or nil
Happy? - boolean (default to true)
Phone - string or nil

Normally you’d do the following:

defmodule Person do

  @enforce_keys [:name]
  defstruct name: nil,
            age: nil,
            happy?: true,
            phone: nil

  @type t() :: %__MODULE__{
          name: String.t(),
          age: non_neg_integer() | nil,
          happy?: boolean(),
          phone: String.t() | nil
        }
end

As you can see, the names of the keys and defaults are separate from the type information. This can get pretty hairy if you have a large, complex data structure and is very unintuitive if you aren’t already familiar with type specs. Luckily, I stumbled upon the TypedStruct package, which is a compile-time macro that dramatically improves the syntax. Using TypedStruct, the above example would look like this:

defmodule Person do
  use TypedStruct

  typedstruct do
    field :name, String.t(), enforce: true
    field :age, non_neg_integer()
    field :happy?, boolean(), default: true
    field :phone, String.t()
  end
end

Now we’re talking! This is immediately understandable to anyone coming across it, particularly if you’re used to the DSL used to define schemas in Ecto.

So then what happens when I use the struct improperly?

defmodule PersonUser do
  @spec init_person() :: Person.t()
  def init_person do
    %Person{name: nil, age: -1, happy?: "yes"}
  end
end

NeoVim, configured properly with Coc.nvim, gives me a popup warning message:

And VSCode, with the Elixir-LS extension, will do the same:

In an ideal world, the program wouldn’t compile. But this is still a huge help, particularly in a large codebase that you’re not completely familiar with.

Upcoming Phoenix Authentication Solution

2020-04-02T00:00:00+00:00

I’m in the middle of writing an application in Elixir and Phoenix, so when I saw a link to an article by José Valim on an upcoming authentication solution for Phoenix, my initial reaction (before reading it) was negative. José is the author of the Devise framework for Ruby-on-Rails, so I assumed it was going to be the same idea, but for Elixir and Phoenix. I’ve implemented Devise in a handful of Rails apps, and each and every time I ended up ripping it out and writing my own auth solution (often based on this Railscasts tutorial). The reason is that while authentication works similarly in most apps, there are always 1 or 2 business requirements that fall outside of what Devise can do in a simple and straightforward manner. Yes, Devise is very flexible there are hooks to add logic and a number of extensions available, but that makes for code that is hard to follow and understand. And something as crucial as authentication needs to be well understood by the maintainers of any web application.

But to my great satisfaction, José said exactly this!

While this made Devise more flexible and general purpose, it also made it more complex. A complex codebase is harder to be audited, which is important in authentication systems. Furthermore, the existence of too many options and customization hooks makes it extremely hard to guarantee that the authentication system will continue be secure under all possible customization combinations.

His authentication “solution” is not a framework, but a code generator. It gets you started with the basic code you need to roll your own authentication. It’s not finished yet, but I’ve looked over the code and it’s exactly what I’ve been wanting for Phoenix. It will make spinning up a new app dramatically simpler. 👏

JavaScript Sprinkles with AlpineJS

2020-03-24T00:00:00+00:00

I’m a big of ReactJS, but sometimes it is way too heavy for what I need. The majority of the applications I create are server-rendered and just need some “sprinkles” of JavaScript. In the past, I’ve leaned on jQuery for this, but I’m not a fan of the imperative nature of it.

Recently, I stumbled upon AlpineJS, which is a super minimalist framework that lets you write declarative sprinkles of JavaScript without resorting to something heavier like React or Vue. It comes in at just 6.4kb (compressed), less than a quarter of the size of Vue, React, or jQuery. And everything is done inline within your HTML, so, like React, your logic is co-located with your markup. Unlike React and Vue, AlpineJS does not use a virtual DOM and relies and the actual DOM.

So for a dead simple example, let’s say you wanted a button that toggled a piece of content. You use the x-data attribute to declare your component scope and initial data, x-show to toggle your content, and x-on:click to add the click behavior.

<div x-data="{isOpen: false}">
  <button x-on:click="isOpen = true">Show Content</button>
  <p x-show="isOpen">Content goes here.</p>
</div>

That’s it! Simple and easy to follow. If we wanted to add a little pizazz, we could use x-show.transition instead and this will animate our content when it’s shown and hidden.

My only real complaint with this, which is the same complaint I have about Angular (1.x) and Vue, is the placement of logic inside strings. The programming purist in me is not a fan of this, but I know it makes sense from a practical standpoint given the historical baggage of HTML.

Let’s move on to a slightly more complex example. Here we’ll keep the value of a text input in sync with the text in a <p> tag. The x-model attribute is used for input 2-way binding and x-text is used for outputting the variable.

<div x-data="{fullName: ''}">
  <label>Full Name</label>
  <input x-model="fullName" />
  <p x-text='fullName'></p>
</div>

But let’s say we want to prefix the name with “My name is” and only show it when the name has been filled in. We’ll use the x-if attribute on a <template> tag.

<div x-data="{fullName: ''}">
  <label>Full Name</label>
  <input x-model="fullName" />
  <template x-if="fullName.length > 0">
    <p>My name is <span x-text='fullName'></span></p>
  </template>
</div>

Lastly, let’s do about as complex of an example as I’d recommend with Alpine. We’ll loop over an array of users and display them in a table along with a form to add another user.

<div x-data="{newUser: { name: '', age: 10 }, users: [{name: 'John', age: 30}, {name: 'Mary', age: 40}]}">
  <table>
    <thead>
      <tr>
        <th>Name</th>
        <th>Age</th>
      </tr>
    </thead>
    <tbody>
      <template x-for="user in users" :key="users">
        <tr>
          <td x-text="user.name" />
          <td x-text="user.age" />
        </tr>
      </template>
    </tbody>
  </table>
  <div>
    <p>
      <label for='name'>Name</label>
      <input id='name' type='text' x-model='newUser.name' />
    </p>
    <p>
      <label for='age'>Age</label>
      <select id='age' x-model='newUser.age'>
        <option value='10'>10</option>
        <option value='20'>20</option>
        <option value='30'>30</option>
        <option value='40'>40</option>
        <option value='50'>50</option>
        <option value='60'>60</option>
        <option value='70'>70</option>
        <option value='80'>80</option>
        <option value='90'>90</option>
        <option value='100'>100</option>
      </select>
    </p>
    <p>
      <button x-on:click="users.push(newUser); newUser = {name: '', age: 10};">Add User</button>
    </p>
  </div>
</div>

Like I said, this is about as complex as you’d want to get with Alpine. But I think that’s a feature, not a bug. Sometimes when you use something as powerful as React or Vue, it’s tempting to push more and more of your app into that paradigm, all while forgetting that there are rough edges around doing so.

Enable Spell Checking in Vim for Markdown and Git Commit Messages

2019-10-21T00:00:00+00:00

I had a ridiculous typo in a Git commit message recently, so I decided to explore spell checking in Vim. As it turns out, it’s extremely easy.

I only wanted it enabled for Git commit messages and markdown, so I added the following to my vimrc / init.vim:

" Spell-check Markdown files and Git Commit Messages
autocmd FileType markdown setlocal spell
autocmd FileType gitcommit setlocal spell

By doing this, it highlights potential misspellings in red underline. You can see a list of potential corrections by moving the cursor over the word in normal mode and pressing z=. Or you can add the word to the dictionary by pressing zg.

While trying this out, I also discovered that you can enable dictionary auto-completion using Vim’s normal ctrl-n and ctrl-p. To enable this (again, for select file types), add the following to your vimrc / init.vim:

" Enable dictionary auto-completion in Markdown files and Git Commit Messages
autocmd FileType markdown setlocal complete+=kspell
autocmd FileType gitcommit setlocal complete+=kspell

Then, while in insert mode, type part of a word and hit ctrl-n to start cycling through potential matches and ctrl-p to cycle through in reverse.

Here’s a quick demonstration of both spell check and dictionary auto completion:

Dark Mode and other site updates

2019-10-20T00:00:00+00:00

Inspired by iOS’s new dark mode (and halloween!), I decided to a dark mode to the website using the new prefers-color-scheme media query. It was surprisingly easy to do. After I’d changed the

This took care of 90% of it:

@media (prefers-color-scheme: dark) {
  html {
    background-color: #19222b;
    color: #eee;
  }

  .page-wrapper__inner {
    background-color: #222f3b;
    color: #eee;
  }
}

Using a straight black-and-white background and foreground combo looks too harsh on the eyes, so you want to find a gray-ish background. Mine is a bluish-grayish color that matched well with some of the existing highlight colors on the site.

Then it was a matter of browsing through the site and finding UI elements that didn’t look right. It took me less than 30 minutes in total.

Also, I decided to merge my blog, which was split into “articles” and “work journal” entries, back together. It was more trouble than it was worth. Sorry if this messed up the RSS feed.

In case you’re on an OS or browser that doesn’t support prefers-color-scheme, here’s a screenshot:

Quickly Convert 4 Spaces (or Tabs) to 2 spaces in Vim

2019-10-19T00:00:00+00:00

Here’s a handy Vim command that I find myself searching for often. It could easily be made into a function in your vimrc.

" 4 spaces to 2 spaces
%s;^\(\s\+\);\=repeat(' ', len(submatch(0))/2);g

" Tab to 2 spaces
%s/\t/  /g

Get the Previous Expression Value in IEx

2019-09-09T00:00:00+00:00

When using Elixir, I’ve long missed the special _ helper from irb that returns the result of the previous expression. Sometimes I actually type it out of pure habit.

Little did I know that Elixir has the same thing, except better.

IEx.Helpers has a function v(n \\ -1) that returns the value of the nth expression in the session history. So v alone returns the previous expression and v(-2) returns the one before it.

iex(1)> "abc"
iex(2)> "zyx"
iex(3)> v
"zyx"
iex(4)> v(-3)
"abc"

Ruby Symbol and String Array Shorthand

2019-08-27T00:00:00+00:00

Ruby has some handy Array shorthands, but I always forget which is which, so I thought I should write them down.

Symbol Array Shorthand:

%i{foo bar}  # => [:foo, :bar]

String Array Shorthand:

%w{foo bar}  # => ["foo", "bar"]

Both also work with square brackets %w[a b c] or parenthesis %i(a b c)

Running Elixir tests in VSCode

2019-07-30T00:00:00+00:00

In Vim-land, I use the vim-test plugin for quickly executing tests from a command line shortcut¹. I wanted to reproduce this behavior in Visual Studio Code, but I couldn’t find an extension that worked in multiple languages (namely, Ruby, Elixir, Javascript, and Elm). I’m mostly just using VSCode for Elixir, but I still liked the idea of finding a more general purpose solution.

So instead I used VSCode’s support for Tasks to build the functionality myself. So in my project’s tasks.json file, I have the following 3 tasks for running all tests, a single test (whatever is under the cursor), and the current file’s tests.

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "mix test",
      "type": "shell",
      "group": "test",
      "command": "mix test",
      "presentation": {
        "echo": true,
        "reveal": "always",
        "focus": false,
        "panel": "shared",
        "clear": true
      }
    },
    {
      "label": "single test",
      "type": "shell",
      "group": "test",
      "command": "mix test ${relativeFile}:${lineNumber}",
      "presentation": {
        "echo": true,
        "reveal": "always",
        "focus": false,
        "panel": "shared",
        "clear": true
      },
      "runOptions": {
        "reevaluateOnRerun": false
      }
    },
    {
      "label": "test current file",
      "type": "shell",
      "group": "test",
      "command": "mix test ${relativeFile}",
      "presentation": {
        "echo": true,
        "reveal": "always",
        "focus": false,
        "panel": "shared",
        "clear": true
      },
      "runOptions": {
        "reevaluateOnRerun": false
      }
    }
  ]
}

Next, I setup keyboard shortcuts to run these. You can access this json file by going to Preferences –> Keyboard Shortcuts, and then clicking the {} icon. I used alt-t and alt-shift-t for single test and current file, respectively. I didn’t create one for running all of the tests because I don’t do that frequently enough to warrant a shortcut.

    {
        "key": "alt+t",
        "command": "workbench.action.tasks.runTask",
        "args": "single test",
        "when": "editorLangId == elixir"
    },
    {
        "key": "alt+shift+t",
        "command": "workbench.action.tasks.runTask",
        "args": "test current file",
        "when": "editorLangId == elixir"
    },

I have an article about this, but my setup has since changed to use this plugin instead. ↩

SSH Tunnels into Production Rails Database

2019-07-25T00:00:00+00:00

Today I needed to access a production database for my Rails app directly using a GUI application on my mac, so I figured out that this can be done by creating an SSH tunnel like so:

ssh -Ng -L <local-port>:<remote-host>:<remote-port> <user>@<remote-host>
ssh -Ng -L 3307:100.64.26.11:3307 adam@100.64.26.11

And then, in your Rails app, update the database.yml as if you were connecting to a local database, but specify the proper database name.

development:
  adapter: mysql2
  database: myapp_production
  host: 127.0.0.1
  port: 3307
  username: root
  password: secret
  encoding: utf8

Rails presence method

2019-07-24T00:00:00+00:00

I use Rails’ present? method constantly, but recently I stumbled across the presence method.

In the past, I have often found myself doing the following because params[:foo] could be nil or a blank string.

foo = params[:foo].present? ? params[:foo] : "something else"

I hate that i have to write params[:foo] twice. But the presence method is handy for this case. It returns nil if the item is nil or a blank string, but otherwise returns the value.

foo = params[:foo].presence || "something-else"

VSCode + ElixirLS = 👍👍

2019-07-24T00:00:00+00:00

I’ve played around with VSCode here and there, but as a fairly picky Vim user who doesn’t do TypeScript, I never quite understood the hype.

Today I started up a new Elixir / Phoenix project (more on that to come) and tried out the Elixir Language Server Extension and the integration is very impression. Code completion, debugger support, automatic inference of Dialyzer Typespecs, documentation on hover, and more….

I don’t expect to be using VSCode as my standard editor (again, picky Vim user¹), but I think I’ll stick with it on Elixir projects.

The vim-mode extension has improved dramatically, but still not quite like the real thing ↩

Netlify Analytics First Impressions

2019-07-23T00:00:00+00:00

My new website is hosted on Netlify, which is an awesome service for hosting static websites. Recently, they launched an Analytics Platform as an alternative to Google Analytics. My impressions of this new tool isn’t quite as enthusiastic as their service in general, but it does have some nice features.

Pros:

Server Side

Can’t be blocked by Ad-Blockers
Tracks requests of non-web-page assets like RSS feeds, images, etc
No impact on your client side performance since there’s no Javascript library

Privacy Centric

Isn’t connected to an ad network that’s building a database of what sites you’re browsing

Cons:

Server Side

You can’t track any user behavior via Javascript. I never do this anyway, but many sites do.

Extremely barebones

No way to filter users by geography, browser, OS, etc
No way to exclude people by IP address. I generally like to exclude my house and my office.
No way to track conversions / goals

Expensive!

$9/month is expensive for such a barebones feature set. Particular when compared to $0 for Google Analytics.
This is somewhat mitigated for me by the fact that my site falls under the free tier of their hosting service.

Conclusion:

I like the general premise of Netlify Analytics, but given the lack of features and price, I suspect that I’ll cancel it off after a month or two. But I’d wager that this is just the MVP for what will eventually become a much more comprehensive tool. So perhaps check back in a year.

TIL: Pass in an ActiveRecord Object to a where string

2019-07-22T00:00:00+00:00

I’m surprised I didn’t already know this, but if you have an ActiveRecord where statement that references an id column, you can just pass in an object and it will pass in the object’s id, not the string representation of the object.

company = Company.find(1)

User.where("users.company_id = ?", company)
# is equal to
User.where("users.company_id = ?", company.id)

So when you create named scopes, you don’t have to do the song-and-dance where you check to see if the object is a model or an integer, as shown below.

scope :by_company, lambda { |company|
    company_id = company.is_a?(Company) ? company.id : company
    where( "users.company_id = ?", company_id )
  }
}
# You wouldn't actually want to use a string in this example.
# Try to only use strings in very complex scopes and queries.

Lookup IP Address & Location via the Command Line

2019-07-21T00:00:00+00:00

With ifconfig.co, you can lookup your external IP Address and Location Information using a simple curl command. You can use it like so:

$ curl ifconfig.co/json
{
  "ip": "96.27.202.202",
  "ip_decimal": 1612409628,
  "country": "United States",
  "country_iso": "US",
  "city": "Columbus",
  "hostname": "d27-96-101-101.nap.wideopenwest.com"
}

$ curl ifconfig.co/city
Columbus

$ curl ifconfig.co/country
United States

Website Revamp! And introduction to my Work Journal.

2019-07-20T00:00:00+00:00

My website has gone slightly stagnent lately, so I decided that it was time for a revamp. There were a few things I didn’t like about the old website:

As a developer with some design chops, I never liked the fact that I hadn’t designed my website myself. I was using the Hyde theme for Jekyll.
I felt boxed in by the fact that all my previous posts were longer-form articles.
While Jekyll is a great tool, it’s very blogging-centric, and I wanted to add new types of content.

So I re-designed the website from scratch using Middleman. I started with Thoughtbot’s base Middleman template, but I changed quite a bit from there. And all the design is custom. I’m pretty happy with the result. And finally, I added a “Work Journal”, where I plan to write shorter, more informal posts on what’s going on in my work. That could be something I learned, a book I just read, a status update on a side project, etc.

Exciting things to come!

Run your Ruby tests quickly and easily using Vim and Tmux

2016-02-01T00:00:00+00:00

In order for testing to become part of your development workflow, it needs to become a habit. And like any habit, its biggest enemy is neglect. Too often I’ll be in a rush and not add tests to my code for a day, and that turns into a week and then a month, and suddenly I have an app where half of my codebase is untested and the other half has breaking tests. There are many things you can do to help keep this habit (hooking up a CI server immediately comes to mind), but an important one is to make running your tests as quick and easy as possible.

One way I do this is by making my ruby tests (either Rspec or Minitest) extremely easy to run while I’m using Vim (and Tmux). With one quick keystroke, I can run the current test file or individual test in a new Tmux pane.

To set this up, first install the following 2 Vim plugins using a plugin manager such as NeoBundle or Vundle.

Vimux: Enables Vim to interact with Tmux
Turbux: Run ruby tests from Vim

Next, you’ll probably want to configure your test command to be prefixed with bundle exec, so add the following to your Vimrc:

let g:turbux_command_prefix = 'bundle exec'

Now that everything is installed (and you’ve reloaded Vim if needed), you can open your first test file. Then just hit <leader> t to run all of the tests. It will then open up a new tmux pane (or reuse an existing one if already open) and run them just as if you had run the command yourself. And then if you want to run a single test at a time, move the cursor to inside the test and hit <leader> T.

You can change these default keyboard shortcuts if you’d like. Here’s what I use:

let g:no_turbux_mappings = 1
map <leader>t <Plug>SendTestToTmux
map <leader>s <Plug>SendFocusedTestToTmux

By combining these handy shortcuts with the speed increase provided by Spring, the application preloader added in Rails 4.1, you’ll have no excuse not to be running your tests quickly and frequently.

Here’s a quick gif of how the whole process looks:

Authentication with JSON Web Tokens using Rails and React / Flux

2015-07-20T00:00:00+00:00

In a previous post, I went over how to add authentication to your Rails + Angular app using JSON Web Tokens (JWT). This time, I’ll do the same, but using the React ecosystem. But even if you’re using another front-end framework (Angular, Ember, Backbone), this post will be helpful because it fixes some issues with the previous server-side code that broke due to a change in the jwt gem.

As I mentioned last time, I am a huge proponent of rolling your own authentication. It is not particularly complicated, plus I have found that the flexibility of a custom solution almost always comes in handy down the road and more than makes up for the up-front time-savings.

Before getting started, you should go back and read the first 2 sections (Overview and Client/Server Data Flow) of the previous post because I’m not going to repeat this information. Also, this tutorial assumes you already have a user model that includes a username and password.

Server Side

To get started, you’ll first need to install the jwt gem.

Next, let’s create a very simple abstraction for encoding and decoding auth tokens. So let’s create a file at lib/auth_token.rb and add the following code:

class AuthToken
  # Encode a hash in a json web token
  def self.encode(payload, ttl_in_minutes = 60 * 24 * 30)
    payload[:exp] = ttl_in_minutes.minutes.from_now.to_i
    JWT.encode(payload, Rails.application.secrets.secret_key_base)
  end

  # Decode a token and return the payload inside
  # If will throw an error if expired or invalid. See the docs for the JWT gem.
  def self.decode(token, leeway = nil)
    decoded = JWT.decode(token, Rails.application.secrets.secret_key_base, leeway: leeway)
    HashWithIndifferentAccess.new(decoded[0])
  end
end

The code is fairly straightforward. Note that the decode method could potentially raise on of several exceptions, so any calling code should account for this.

Next, we need to implement the endpoint used by our login form. So create a new controller called AuthController with a single authenticate action. What it will do is verify the username and password and, if correct, create a new auth token that the client can then use to make authenticated requests. We implemented the authentication_payload method separately because we’re going to reuse it later.

class AuthController < ApplicationController
  def authenticate
    # You'll need to implement the below method. It should return the
    # user instance if the username and password are valid.
    # Otherwise return nil.
    user = User.find_by_credentials(params[:username], params[:password])
    if user
      render json: authentication_payload(user)
    else
      render json: { errors: ['Invalid username or password'] }, status: :unauthorized
    end
  end

  private

  def authentication_payload(user)
    return nil unless user && user.id
    {
      auth_token: AuthToken.encode({ user_id: id }),
      user: { id: user.id, username: user.username } # return whatever user info you need
    }
  end
end

And add a route to your routes.rb file to make it accessible:

post 'authenticate' => 'auth#authenticate'

Next, we need a way to authenticate each request and also find out who the current user is. We’ll add this code to our ApplicationController, exposing authenticate_request! and current_user methods to the rest of our controllers.

class AccessDeniedError < StandardError
end
class NotAuthenticatedError < StandardError
end
class AuthenticationTimeoutError < StandardError
end

class ApplicationController < ActionController::API
  attr_reader :current_user

  # When an error occurs, respond with the proper private method below
  rescue_from AuthenticationTimeoutError, with: :authentication_timeout
  rescue_from NotAuthenticatedError, with: :user_not_authenticated

  protected

  # This method gets the current user based on the user_id included
  # in the Authorization header (json web token).
  #
  # Call this from child controllers in a before_action or from
  # within the action method itself
  def authenticate_request!
    fail NotAuthenticatedError unless user_id_included_in_auth_token?
    @current_user = User.find(decoded_auth_token[:user_id])
  rescue JWT::ExpiredSignature
    raise AuthenticationTimeoutError
  rescue JWT::VerificationError, JWT::DecodeError
    raise NotAuthenticatedError
  end

  private

  # Authentication Related Helper Methods
  # ------------------------------------------------------------
  def user_id_included_in_auth_token?
    http_auth_token && decoded_auth_token && decoded_auth_token[:user_id]
  end

  # Decode the authorization header token and return the payload
  def decoded_auth_token
    @decoded_auth_token ||= AuthToken.decode(http_auth_token)
  end

  # Raw Authorization Header token (json web token format)
  # JWT's are stored in the Authorization header using this format:
  # Bearer somerandomstring.encoded-payload.anotherrandomstring
  def http_auth_token
    @http_auth_token ||= if request.headers['Authorization'].present?
                           request.headers['Authorization'].split(' ').last
                         end
  end

  # Helper Methods for responding to errors
  # ------------------------------------------------------------
  def authentication_timeout
    render json: { errors: ['Authentication Timeout'] }, status: 419
  end
  def forbidden_resource
    render json: { errors: ['Not Authorized To Access Resource'] }, status: :forbidden
  end
  def user_not_authenticated
    render json: { errors: ['Not Authenticated'] }, status: :unauthorized
  end
end

Now, for any protected method, add authenticate_request! to the beginning of the action method or in a before action filter.

Client Side

Now let’s switch to the client side. First, we’ll create a module that wraps our authentication api request. Next, we’ll need to implement a way to store our session info so that our React components can access it. And finally we’ll create our login form component.

Note that this will only cover the bare minimum of what you’ll probably need. Among topics that won’t be covered are persisting the session to local storage (so that they can come back later and still be logged in) and renewing the session when it expires.

Also, note that I’m using ES6 (or ES2015, as some like to call it) in all of my javascript code, transpiled using babel. I’m a long-time Coffeescript user, but I highly recommend moving towards ES6. It brings many of Coffeescript’s great features, plus the community as a whole is migrating towards it very quickly.

Auth API Wrapper

For my react apps, I use the axios http library. But you can use any library you’d like. This is just a simple method that makes an HTTP Post request to the server-side endpoint we just created.

auth_api.js:

import axios from 'axios';

const loginPath = '/api/authenticate';

let AuthAPI = {
  login(username, password) {
    return new Promise(function(resolve, reject) {
      axios.post(loginPath, {username: username, password: password})
        .then((resp) => resolve(resp.data))
        .catch((errResp) => reject(errResp.data));
    });
  }
};

export default AuthAPI;

Session Managment using Flux

Before we implement our login form component, we need a way to maintain the state of our user session. The best way to do this is to implement the Flux pattern. If you are new to the Flux pattern, you should read up on it first, but it is essentially a circular data flow that starts with your View, which triggers various Actions, which are responded to by your Stores who then update the application state, to which your View changes accordingly. And then this process repeats for each user action.

For example, by clicking on our logout link component (the view), the logout action is triggered. Then the session store listens to this action and responds by clearing out the user and session info. Then the view, which is listening to changes on the session store, responds by hiding the logout link and showing the login link instead.

There are a number of Flux implementations out there, but I’ll use Reflux because it is simple and contains very little boilerplate code. So install it using NPM and then create two files: auth_actions.js and session_store.js. I think there’s some debate as to where data requests should originate within the flux architecture, but I’m going to go with Reflux’s suggestion of putting them in the Store.

auth_actions.js:

import Reflux from 'reflux';
let AuthActions = Reflux.createActions({
   // asyncResult creates 2 extra actions, one for success and one for failure
  'loginRequest': { asyncResult: true },
  'logout': { }
});
export default AuthActions;

session_store.js:

import Reflux from 'reflux';
import AuthActions from './auth_actions';
import AuthAPI from './auth_api';

// This object is where we'll store all the session state.
// It will be a private variable and if any outside code
// wants to access it, they'll need to use one of the
// accessor methods below.
let _sessionState = {
  authRequestInProgress: false,
  authErrors: [],
  authToken: null,
  username: null,
  userId: null
};

let SessionStore = Reflux.createStore({
  // Map all the actions in AuthActions to the corresponding
  // methods below
  listenables: [AuthActions],

  // When a login request occurs, use the AuthAPI to make
  // an api request to the server and call the appropriate
  // action when it finishes.
  // Trigger a change to alert subscribers about the fact
  // that a request is in progress.
  onLoginRequest (username, password) {
    _sessionState.authRequestInProgress = true;
    AuthAPI.login(username, password)
      .then(AuthActions.loginRequest.completed)
      .catch(AuthActions.loginRequest.failed);
    this.trigger(_sessionState);
  },

  // When a login request completes successfully,
  // set the user info to the session state object and
  // trigger a change
  // an api request to the server and call the appropriate
  // action method when it finishes.
  onLoginRequestCompleted (resp) {
    _sessionState.authRequestInProgress = false;
    _sessionState.authErrors = [];
    _sessionState.authToken = resp.auth_token;
    _sessionState.username = resp.username;
    this.trigger(_sessionState);
    // You'll also need to redirect the user to the proper page,
    // but that's outside the scope of the article
  },

  // When a login request fails, set the auth errors
  // and trigger a change
  onLoginRequestFailed (resp) {
    _sessionState.authRequestInProgress = false;
    _sessionState.authErrors = resp.errors;
    this.trigger(_sessionState);
  },

  // When the user logs out, clear out the session state
  // and trigger a change
  onLogout () {
    _sessionInfo = {
      authRequestInProgress: false,
      authErrors: [],
    };
    this.trigger(_sessionState);
  },

  // Accessor Methods
  getUsername() { return _sessionState.username; }
  getUserId() { return _sessionState.userId; }
  isLoggedIn() { return (_sessionState.authToken !== null); },
  getAuthErrors() { return (_sessionState.authErrors); },
  isAuthRequestInProgress() { return (_sessionState.authRequestInProgress === true); }
});

export default SessionStore;

Now we need a simple login form component. Upon submission, it will trigger the loginRequest auth action, passing along the captured username and password.

import React from 'react';
import AuthActions from './auth_actions.js';
import SessionStore from './session_store.js';

let LoginForm = React.createClass({
  handleLogin(e) {
    e.preventDefault();
    let username = this.refs.username.getDOMNode().value.trim();
    let password = this.refs.password.getDOMNode().value.trim();
    AuthActions.login(username, password);
  },
  renderAuthErrors() {
    let errors = SessionStore.getAuthErrors();
    if (errors.length === 0) { return null; }
    return (
      <ul className='AuthErrors'>{ errors.map((err) => ( <li>{err}</li> )) }</ul>
    );
  },
  render() {
    let buttonText = SessionStore.isAuthRequestInProgress() ? 'Submitting...' : 'Login';
    return (
      <form onSubmit={this.handleLogin}>
        { this.renderAuthErrors() }
        <input type='text' name='username' ref='username' />
        <input type='password' name='password' ref='password' />
        <button disabled={SessionStore.isAuthRequestInProgress()}>{buttonText}</button>
      </form>
    );
  }
});

export default LoginForm;

Now let’s create a “UserControls” component that, when logged in, will show the user’s username and a link to logout. Otherwise, it will show a link to the login page.

import React from 'react';
import SessionStore from './session_store.js';
import AuthActions from './auth_actions.js';

let UserControls = React.createClass({
  handleLogout(e) {
    e.preventDefault();
    AuthActions.logout();
  },
  render() {
    if (SessionStore.isLoggedIn()) {
      return (
        <div className='UserControls'>
          <span>{SessionStore.getUsername}</span>
          <a href='#' onClick={this.handleLogout}>Logout</span>
        </div>
      );
    } else {
      return (
        <div className='UserControls'>
          <a href='#/login'>Login</a>
        </div>
      );
    }
  }
});

export default UserControls;

Finally, we need to configure Axios with a request “interceptor” so that it includes our auth token in the ‘Authorization’ header of every subsequent API request. This token is extracted and verified by our server so it knows the identity of the user. You’ll want to call this code as soon as your client app is initialized.


import SessionStore from './session_store.js';

export default function() {
  axios.interceptors.request.use(function (config) {
    config.headers.Authorization = 'Bearer ' + SessionStore.getAuthToken();
    return config;
  });
}

Conclusion

As I said above, there are still some pieces missing that are outside the scope of this article, but this should at least get you started towards a nice auth experience in your Rails / React application. This code was somewhat roughly extracted from an existing codebase, so if you find any problems, let me know on twitter. Thanks!

How to Replace the Angular Stack with React plus a few NPM modules

2015-07-17T00:00:00+00:00

As you can tell from the content of my blog posts, I’ve been practicing and preaching Angular.js for quite some time now. It is an extremely productive web framework that felt like a big step forward from my days doing jQuery “sprinkles” and then Backbone.

But then recently, I started playing with Facebook’s React framework. And while I’m still not quite as productive as I was with Angular, I absolutely love the code that I’m writing. And on top of that, it has opened my eyes to a whole new paradigm for creating user interfaces.

I won’t make this an article comparing and contrasting the libraries (a google search will probably turn up dozens of these), but here are the main reasons I’ve made the switch:

Small API surface area - you can learn 90% of React in 1 day (unlike Angular, where this is the common learning experience)
Due to the efficiency of the virtual DOM, you don’t have to worry about updating the DOM. You just write a single render() function that is run over and over and applied in an efficient manner. It makes writing your views more similar to how you’d write them on the server because your view is simply a reflection of your current state. Angular’s 2-way binding is nice, but it comes at a cost of speed and complexity.
The “Everything is a component” paradigm is an extremely pleasant and simple way to create user interfaces.
Everything is just javascript. Even the “templates”.

And I’m sure there are others. Angular is still a great framework, but at the end of the day, I enjoy writing code in React quite a bit more. And interestingly enough, while I had previously been under the impression that React was a 1-trick pony that you used when performance was a big requirement, the fact that it’s extremely fast probably wouldn’t make the top 10 reasons why I would pick it over other frameworks.

One of the biggest differences between the two libraries is their scope (and this can be both good and bad). React only provides the view layer, while Angular provides quite a bit more, such as libraries for promises, http, dependency injection, etc, etc.

So how do we replace all these concepts in the React world? Let’s go over them one by one.

Routing

Angular has a new router that I hear is great, but all my experience had been with UI-Router, which I generally liked. There is a React-focused router called react-router that is really fantastic. It is highly inspired by Ember’s built-in router, but uses React’s JSX syntax to structure your routes.

Promises

Promises are in most JS apps these days and ES6 (the next version of Javascript) will have built-in promises, but until then, we will need to use a library. Angular includes the very nice $q library that, as of version 1.3, uses a syntax fairly similar to that of ES6. For a non-Angular project, we have a few choices. First, there is es6-promise, which is a polyfill that just includes the exact functionality that ES6 will have. But there was one feature that I missed from $q, which was the finally() method. So if you need this feature, I recommend the Bluebird library.

HTTP Requests

For my early Angular projects, I used Restangular, but in later projects, I found myself just using $http with a service for each resource. Axios is a library that is very similar to (and, in fact, inspired by) $http. Like $http, it is promise-based, automatically transforms JSON, and allows you to setup request and response interceptors.

Modules / Dependency Injection

Angular includes its own dependency injection framework for importing other libraries. It has a quirky syntax, but it generally works pretty well. But it is Angular-only, so it can be a bit awkward to pull in 3rd party libraries that weren’t built for Angular. In React, you can just use NPM modules, which are widely supported, by using a bundling library such as WebPack or Browserify (I suggest Webpack). Then you can just require other modules like so:

var otherLib = require('some-other-library');

Unit Testing & Mocking

Easy unit testing is one of my favorite things about Angular, so it’s great to know that their test runner, Karma, isn’t specific to angular and can just as easily be used with React.

Facebook actually has their own test runner and flavor of Jasmine called Jest, which has two things going for it: It’s easy to setup and it auto-mocks your dependencies by default. But I found it to be painfully slow and quickly switched to Mocha plus Chai and running tests using Karma. And there are a few testing helper libraries included in React that can be used with any framework.

Conclusion

When I first moved from server-generated “traditional” web apps (and some light backbone apps) over to Angular, it felt like a huge step forward. While moving to React may not be as big of a step in terms of productivity, it feels like a huge move forward in terms of code simplicity and cleanliness. I’m officially a convert, and I highly suggest that you check it out. And now that you know the basics of the React ecosystem, there’s no excuse not to give it a try.

Authenticating your Angular / Rails App with JSON Web Tokens

2014-12-04T00:00:00+00:00

UPDATE: There have been some changes in the JWT Gem that make some of the below not work exactly right (it’ll still be about 90% the same). Specifically, they added expiration support. See my post on the same topic, but using React.js. The server side code in this post will work just as well with Angular.

Overview

I’m a big proponent of rolling your own authentication solution, especially if you’re only doing simple username/password based logins (as opposed to logging in via an OAuth provider). I’ve tried to use Devise on a number of Rails apps, but I always end up ripping it out. It’s not because Devise is a bad gem, but because it always takes me more time to customize it to my liking than it does to just write everything myself. And the flexibility of a custom solution almost always comes in handy down the road. I have generally implemented it the same way that Ryan Bates does in this Railscasts episode.

But now that most of my greenfield projects are single page javascript apps, authentication has become slightly more complicated. While you can certainly continue doing traditional authentication with cookies and server-rendered views, my preference is to use a token-based approach. This has a number of benefits:

The same authentication API can be used by all types of clients (web app, mobile app, etc).
It is stateless, so the web server does not have to keep track of session information, which is good for scaling.
Protected against CSRF (cross-site request forgery) attacks
All of your views are rendered by the client, rather than a mix of server and client rendered views.

A relatively new standard for accomplishing this is JSON Web Tokens (abbreviated to JWT). I won’t dig into the details because there are plenty of good resources, but JWT is a way of digitally signing data to be transferred between two parties. The data is represented as an encoded JSON object. In a nutshell, these tokens are passed to the client upon successful authentication and then subsequently used in every HTTP request in order to verify the identity of the client.

Client/Server Data Flow

So the application flow will look something like this:

Client sends username and password to server.
If credentials are valid, the server generates a token that include’s the user’s ID inside the token payload. (Remember, this payload is not encrypted - the client can read it - so don’t put anything you don’t want the client to see)
The token is returned to the client, who saves it somewhere for later use.
When the client makes a request for protected data from the server, it includes the token in an HTTP header.
Upon receiving a request for protected data, the server looks at the token and verifies that it was indeed generated for the user represented by the ID in the payload.

Server-Side Code

So let’s start with the server-side code and assume you already have a basic user model. We’ll first need some code to generate a JWT for a given user. So install the jwt gem into your Gemfile. Next, I found there to be fair amount of logic around the JWT auth tokens, so I extracted it into a simple AuthToken class that takes care of encoding and decoding the tokens for us.

class AuthToken
  def self.encode(payload, exp=24.hours.from_now)
  payload[:exp] = exp.to_i
  JWT.encode(payload, Rails.application.secrets.secret_key_base)

  def self.decode(token)
    payload = JWT.decode(token, Rails.application.secrets.secret_key_base)[0]
    DecodedAuthToken.new(payload)
  rescue
    nil # It will raise an error if it is not a token that was generated with our secret key or if the user changes the contents of the payload
  end
end

# We could just return the payload as a hash, but having keys with indifferent access is always nice, plus we get an expired? method that will be useful later
class DecodedAuthToken < HashWithIndifferentAccess
  def expired?
    self[:exp] <= Time.now.to_i
  end
end

And let’s add a helper method to our User model that uses this class:

def generate_auth_token
  payload = { user_id: self.id }
  AuthToken.encode(payload)
end

Ok, now we need to take care of that initial authentication request in our Client/Server Data flow. The client sends a username/password combination and the server sends back a new token. So go ahead and create a new controller called AuthController and add a new post route to routes.rb. You may also want to return some information about the current user inside the JSON response, but for now we’ll just return the auth token.

class AuthController < ApplicationController
  skip_before_action :authenticate_request # this will be implemented later
  def authenticate
    user = User.find_by_credentials(params[:username], params[:password]) # you'll need to implement this
    if user
      render json: { auth_token: user.generate_auth_token }
    else
      render json: { error: 'Invalid username or password' }, status: :unauthorized
    end
  end
end

# in routes.rb:
post 'auth' => 'auth#authenticate'

Ok, now we need to add code to validate the token on subsequent requests. What we’ll do first is implement a few helper methods in our ApplicationController that take care of decoding/validating the token and, based on the token payload, finding the current user. Then we’ll tie them all together in a a before filter/action. If the token is properly decoded and the user found, the request can be continued. If not, we’ll return a 401 Unauthorized response.

class ApplicationController < ActionController::Base
  before_action :set_current_user, :authenticate_request

  rescue_from NotAuthenticatedError do
    render json: { error: 'Not Authorized' }, status: :unauthorized
  end
  rescue_from AuthenticationTimeoutError do
    render json: { error: 'Auth token is expired' }, status: 419 # unofficial timeout status code
  end

  private

  # Based on the user_id inside the token payload, find the user.
  def set_current_user
    if decoded_auth_token
      @current_user ||= User.find(decoded_auth_token[:user_id])
    end
  end

  # Check to make sure the current user was set and the token is not expired
  def authenticate_request
    if auth_token_expired?
      fail AuthenticationTimeoutError
    elsif !@current_user
      fail NotAuthenticatedError
    end
  end

  def decoded_auth_token
    @decoded_auth_token ||= AuthToken.decode(http_auth_header_content)
  end

  def auth_token_expired?
    decoded_auth_token && decoded_auth_token.expired?
  end

  # JWT's are stored in the Authorization header using this format:
  # Bearer somerandomstring.encoded-payload.anotherrandomstring
  def http_auth_header_content
    return @http_auth_header_content if defined? @http_auth_header_content
    @http_auth_header_content = begin
      if request.headers['Authorization'].present?
        request.headers['Authorization'].split(' ').last
      else
        nil
      end
    end
  end
end

You’ll also need to define the 2 errors that are being rescued from:

class NotAuthenticatedError < StandardError
end
class AuthenticationTimeoutError < StandardError
end

Client Side Code

That should take care of the server side. Next, we’ll need to add support for these API’s into our angular app. To do this, we’ll need to implement two pieces of code: An AuthService that will handle logging in followed by an HTTP interceptor that will automatically attach our auth token to every http request and handle auth-related error responses.

First, our AuthService. Note that there are two dependencies you’ll need to implement. First, AuthToken is a simple service for storing the auth token in local storage while AuthEvents is a constant with a few auth/login related events so we’re not using magic strings.

app.factory("AuthService", function($http, $q, $rootScope, AuthToken, AuthEvents) {
  return {
    login: function(username, password) {
      var d = $q.defer();
      $http.post('/api/auth', {
        username: username,
        password: password
      }).success(function(resp) {
        AuthToken.set(resp.auth_token);
        $rootScope.$broadcast(AuthEvents.loginSuccess);
        d.resolve(resp.user);
      }).error(function(resp) {
        $rootScope.$broadcast(AuthEvents.loginFailed);
        d.reject(resp.error);
      });
      return d.promise;
    }
  };
});

You’ll need to implement a basic login form and controller that use this service.

Next, let’s add our two http interceptors. The first is quite simple. Just attach “Bearer” followed by the auth token. This is the standard format for adding a JWT to your http headers. The error interceptor is slightly more complicatated. First, we check to make sure this isn’t our intial auth request because we want that to handle errors on its own. Then, we check to see if the response code matches any of our auth-related codes. If so, we broadcast an appropriate event.

app.factory("AuthInterceptor", function($q, $injector) {
  return {
    // This will be called on every outgoing http request
    request: function(config) {
      var AuthToken = $injector.get("AuthToken");
      var token = AuthToken.get();
      config.headers = config.headers || {};
      if (token) {
        config.headers.Authorization = "Bearer " + token;
      }
      return config || $q.when(config);
    },
    // This will be called on every incoming response that has en error status code
    responseError: function(response) {
      var AuthEvents = $injector.get('AuthEvents');
      var matchesAuthenticatePath = response.config && response.config.url.match(new RegExp('/api/auth'));
      if (!matchesAuthenticatePath) {
        $injector.get('$rootScope').$broadcast({
          401: AuthEvents.notAuthenticated,
          403: AuthEvents.notAuthorized,
          419: AuthEvents.sessionTimeout
        }[response.status], response);
      }
      return $q.reject(response);
    }
  };
});

app.config(function($httpProvider) {
  return $httpProvider.interceptors.push("AuthInterceptor");
});

// Elsewhere....

$rootScope.$on(AuthEvents.notAuthorized, function() {
  // ... Take some action in response to a 401
});

How you handle these auth error events will be up to you. The simplest solution is to just redirect the user to the login page. Or you may want to pop up a modal login form so that the user doesn’t lose his or her work.

Also, this naively assumes you’ll have a long session length and the user won’t mind logging in again at the end, even if they’ve been actively using it the whole time. In my app, the session timeout length is just 60 minutes. So I implemented a timer that, every x minutes, requests to reissue the token (thus pushing back the expiration date) so long as there had been recent user activity. I may share this code in a future blog post, but I figured it was out of scope for the time being.

I’d love to hear your feedback because, again, this was roughly extracted from my application and I’m not even sure it’s the best implementation. So let me know on twitter, where I’m @adam_albrecht, if you find any bugs or ways to improve the code. Thanks!

Authorization with Angular.js and UI-Router

2014-09-22T00:00:00+00:00

While working on an angular.js application recently, I found myself needing some form of authorization logic (not to be confused with authentication / login). I needed to restrict content in my app based on a user’s role as well as some other factors. At first, I created a single AuthService service that dealt with login, authorization, and session management. But this felt messy and violated the Single Responsibility Principle, so I decided to make something cleaner. My goal was for the API to look something like this:

(Warning: lots of coffeescript ahead!)

LoginService.login(email, password).then((u) ->
  Session.setCurrentUser(u)
)
# ... Elsewhere ....
user = Session.getCurrentUser()
authorizer = new Authorizer(user)
authorizer.canAccess(APP_PERMISSIONS.viewAdminSettings) # returns a boolean

By doing it this way, I was fairly sure I could split my formerly monolithic AuthService into 3 separate services that had no dependencies on one another. I won’t go too detailed into the login and session services because they are fairly straight forward. LoginService has one method that simply makes an HTTP request with a username and password and, if successful, returns the user object. Session is a singleton service that, given a user, can create or destroy the current session. But my solution to Authorization was fairly interesting, so I thought I’d share.

In the ruby world, I’ve used both CanCan and Pundit and so I drew a lot of inspiration from them. But at the same time, I was mindful that client-side authorization is never as complex as server side. You should never need to use client side authorization to filter data (that should be done server side), but only to show/hide pages and pieces of content.

So first, I created a constant containing a set of permissions:

app.constant('APP_PERMISSIONS', {
  viewAdminSettings: "viewAdminSettings"
  editAdminSettings: "editAdminSettings"
  viewLibrary: "viewLibrary"
  editLibrary: "editLibrary"
  viewBusinessAssociates: "viewBusinessAssociates"
  editBusinessAssociates: "editBusinessAssociates"
  # ...
})

You’ll notice that the keys and values are the same. I only made this an object rather than an array so I could refer to them with a dot syntax and wouldn’t have magic strings floating around.

Next, as a good programmer does, I added a test for the Authorizer service I was about to make.

describe "Authorizer", ->
  Authorizer = null
  APP_PERMISSIONS = null

  beforeEach(angular.mock.module('privacypro.auth'))
  beforeEach(inject((_Authorizer_, _APP_PERMISSIONS_) ->
    Authorizer = _Authorizer_
    APP_PERMISSIONS = _APP_PERMISSIONS_
    return # always add return statements to injection blocks in Coffeescript.
  ))

  describe "canAccess()", ->
    authorizer = null
    describe "An admin user", ->
      user = { role: "admin" }
      beforeEach ->
        authorizer = new Authorizer(user)
      it "can view the admin settings", ->
        expect(authorizer.canAccess(APP_PERMISSIONS.viewAdminSettings)).toBeTruthy()

    describe "A normal user", ->
      user = { role: "normal" }
      beforeEach ->
        authorizer = new Authorizer(user)
      it "cannot view the admin settings", ->
        expect(authorizer.canAccess(APP_PERMISSIONS.viewAdminSettings)).toBeFalsy()
      it "can view the library OR view the admin settings", ->
        expect(authorizer.canAccess([APP_PERMISSIONS.viewLibrary, APP_PERMISSIONS.viewAdminSettings])).toBeTruthy()
      it "throws an error if passed a bad permission", ->
        expect(-> authorizer.canAccess("foobar")).toThrow()

My specs included a number of examples and more complex scenarios, but you get the point. So next, I started work on my Authorizer service. This class can be as simple or complex as your authorization requirements demand. In reality, my code is quite a bit more complex than below, but you’ll understand the basics from this example:

app.service("Authorizer", (APP_PERMISSIONS, USER_ROLES) ->
  return (user) ->
    {
      canAccess: (permissions) ->
        permissions = [permissions] unless angular.isArray(permissions)
        for permission in permissions
          if !APP_PERMISSIONS[permission]?
            throw "Bad permission value"
          if user && user.role
            switch permission
              when APP_PERMISSIONS.viewAdminSettings, APP_PERMISSIONS.editAdminSettings
                return (user.role == USER_ROLES.admin)
              when APP_PERMISSIONS.editLibrary
                return (user.role == USER_ROLES.admin || user.role == USER_ROLES.normal)
              # etc...
          else
            return false
        false
    }
)

Now I’m ready to add permissions to some of my routes. I always use UI-Router, but something similar can be done with ngRoute.

$stateProvider
  .state("library", {
    url: "/library",
    templateUrl: "..."
    data: {
      permissions: [APP_PERMISSIONS.viewLibrary]
    }
  })
  .state("admin", {
    url: "/admin",
    templateUrl: "...",
    data: {
      permissions: [APP_PERMISSIONS.editAdminSettings]
    }
  })

But how do I use this permission data and prevent a state from loading? To do this, you simply have to subscribe to ui-router’s $stateChangeStart event and prevent it from propegating when necessary. Put this code inside of an angular run block.

app.run(($rootScope, Session, Authorizer, AUTH_EVENTS) ->
  $rootScope.$on "$stateChangeStart", (event, next) ->
    permissions = if next && next.data then next.data.permissions else null
    user = Session.getCurrentUser()
    authenticator = new Authorizer(user)
    if permissions? && !authenticator.canAccess(permissions)
      event.preventDefault()
      if !user
        $rootScope.$broadcast AUTH_EVENTS.notAuthenticated
      else
        $rootScope.$broadcast AUTH_EVENTS.notAuthorized

Notes:

AUTH_EVENTS is another constant where I store various auth-related events.
I did test this logic in my e2e tests via Protractor, but I don’t want to make this post too extremely long.

Finally, I needed to restrict individual pieces of content on the page. One easy way to do this would be to create a helper method on the scope and use it in tandem with ngIf like so:

<a href='' ng-if="canAccess('editAdminSettings')">Edit Admin Settings</a>

But this is a bit messy and I hate to pollute the scope unless absolutely necessary. So instead, I created a custom directive that will work similarly:

<a href='' ng-if-permission="editAdminSettings">Edit Admin Settings</a>

I was hoping to simply extend the ngIf directive with a specific set of logic, but I couldn’t find a way to do this (if you know how to do this, please let me know!). So instead, I simply copied the ngIf source code, changed the name to ngIfPermission, and made a few minor enhancements to the link function:

# the beginning is the same besides the name
link: ($scope, $element, $attr, ctrl, $transclude) ->
  block = undefined
  childScope = undefined
  previousElements = undefined

  # There is no logic in the watch, so we can use $attr.$observe instead
  $attr.$observe "ngIfPermission", (value) ->
    # Check if we can access the permission(s)
    permissions = value.split(",")
    user = Session.getCurrentUser()
    authenticator = new Authorizer(user)
    if authenticator.canAccess(permissions)
      unless childScope
        $transclude (clone, newScope) ->
          childScope = newScope
          # change the contents of the placeholder comment
          clone[clone.length++] = document.createComment(" end ngIfPermission: " + $attr.ngIfPermission + " ")

# the rest is the same
)

So now we have a way to restrict access to pages as well as individual pieces of content. Remember, client side authorization is no substitute for proper server-side authorization. Anybody who is half-way decent with the Chrome dev tools can figure out how to manipulate your API requests.

I hope this helps you in your journey to create a complex and full-featured angular app. If you have any questions or have a suggestion on how to improve the code, let me know on twitter, where I’m @adam_albrecht. Thanks!

Building your Angular app with Gulp.js

2014-06-20T00:00:00+00:00

As my work has transitioned from traditional web apps to thick-client Javascript apps (primarily using Angular), Grunt has become essential in my workflow. Grunt is a nice tool and it gets the job done. But there was always something I didn’t like about it that I couldn’t quite articulate until I discovered Gulp.js. Whereas in Grunt, you create a json configuration file, Gulp is just a script. It’s code. And it really fits my programmer brain better. In this post, I’ll convert a basic Gruntfile that compiles and minifies Coffeescript into Gulp.

The Original Gruntfile

The original Gulpfile I’m converting can be found here. It is for an angular datepicker library that I wrote called ngQuickDate. (Side note: I’m in the middle of re-writing this library from the ground up because I no longer like the way it works).

I won’t put the entire file inline, but here are the relevant parts that compile coffeescript files and then minifies them.

coffee: {
  compile: {
    files: {
      "spec/build/specs.js": ["spec/*.coffee"],
      "dist/ng-quick-date.js": ["src/*.coffee"]
    }
  }
},
uglify: {
  my_target: {
    files: {
      "dist/ng-quick-date.min.js": "dist/ng-quick-date.js"
    }
  }
}
// ...
grunt.loadNpmTasks('grunt-contrib-coffee');
grunt.loadNpmTasks('grunt-contrib-uglify');
grunt.registerTask('default', ['coffee', 'uglify']);

It’s pretty straightforward, but I have 2 problems with it. First, my 2 tasks have no knowledge of one another. Coffeescript files are read, compiled, and written to disk. Then another task reads these new files in, minifies them, then writes to disk again. My second problem is that, with a configuration-based approach like this, it is very hard for a beginner to figure out how to modify tasks and add additional logic to them.

So let’s first reproduce the same gruntfile in Gulp.

Simple Gulpfile

var gulp = require("gulp");
var concat = require("gulp-concat");
var coffee = require("gulp-coffee");
var uglify = require("gulp-uglify");
var rename = require("gulp-rename");

gulp.task("js", function() {
  gulp.src(["src/*.coffee"])            // Read the files
    .pipe(
      coffee({bare:true})               // Compile coffeescript
        .on("error", gutil.log)
    )
    .pipe(concat("ng-quick-date.js"))   // Combine into 1 file
    .pipe(gulp.dest("dist"))            // Write non-minified to disk
    .pipe(uglify())                     // Minify
    .pipe(rename({extname: ".min.js"})) // Rename to ng-quick-date.min.js
    .pipe(gulp.dest("dist"))            // Write minified to disk
});
gulp.task("default", function() {
  gulp.start("js");
});

While it’s not any shorter, I find it significantly easier to read and modify without referring to documenation. As you can see, Gulp accomplishes tasks by using streams and piping, which is a great fit for reading source files, performing a number of actions on them, then writing back out to disk. Each action is chained on to the last one and this makes it unecessary to write out to temp files, thus making it quite a bit faster, as well.

Angular Extras in Gulp

If you’ve used Angular for any significant period of time, you’ll know that it’s a bit quirky. First, minification often breaks your app due to the way its dependency injection system works. But luckily there’s a fix for this: ng-min. This library will analyze your source code and add the necessary arrays around function calls to make it minification friendly. For example, it will convert this:

angular.module('whatever').controller('MyCtrl', function ($scope, $http) { ... });

into….

angular.module('whatever').controller('MyCtrl', ['$scope', '$http', function ($scope, $http) { ... }]);

Integrating this into Grunt is easy enough, but you have to do so as an entirely separate task that runs independently of your compilation and minification. In gulp, we can add it into the middle of our chain of compilation/minification actions by adding a couple lines to our Gulpfile:

var ngmin = require("gulp-ngmin"); // NEW
// ...
    .pipe(
      coffee({bare:true})
        .on("error", gutil.log)
    )
    .pipe(ngmin())                    // NEW: Make angular code friendly to minification
    .pipe(concat("ng-quick-date.js"))
// ...

Couldn’t be easier. Next, let’s say we’re also compiling html templates from Jade but we’d like them to pre-load them into Angular’s template cache so we don’t have to make http requests every time. No problem!

var ngmin = require("gulp-angular-templatecache");
// ...
gulp.src(["src/templates/*.jade"])
  .pipe(jade())            // Compile from jade to html
  .pipe(templateCache())   // Convert to JS strings and place in Angular template cache
  .pipe(gulp.dest("dist")) // Write the JS file to disk

But again, it’s easy to add steps in between. Next, let’s take care of the fact that Angular apps often produce html that is not valid html5. We can automatically add data- prefixes to our various angular directive attributes by using the htmlify module:

var htmlify = require('gulp-angular-htmlify');
// ...
  .pipe(templateCache())
  .pipe(htmlify())                // Add data- prefixes to non-html5-valid attributes
  .pipe(gulp.dest("dist"))

As you can see, it’s fairly trivial to make changes to what started as an extremely basic gulp script.

I wrote a couple angular starter templates that use gulp for compilation. One is meant for full web apps while the other is meant for creating angular libraries.

angular-starter-kit - Build thick-client web apps. Be aware, this is pretty opinionated and won’t be for everyone.
angular-lib-template - Build angular libraries

More Resources

Documentation:

Gulp.js Documentation

Common Gulp Utilities:

gulp-concat - Concatenate files
gulp-util - Various gulp utility functions
gulp-clean - Clean out a folder before writing to disk
StreamQueue - Combine multiple streams into one while preserving the order
gulp-if - Apply actions to files that meet certain conditions
gulp-rename - Rename files
gulp-notify - Show native OS notifications on compilation, errors, etc
gulp-connect - Mini web server for running your app

Common Gulp Pre-Processors

gulp-coffee - Compile coffeescript
gulp-ruby-sass - Compile (the ruby version of) sass and scss
gulp-less - Compile less.css
gulp-jade - Compile jade templates
gulp-markdown - Compile markdown

Minification Plugins

gulp-uglify - Minify / uglify code
gulp-minify-html - Minify html
gulp-minify-css - Minify CSS
gulp-imagemin - Compress images without losing quality

Angular Helper Plugins

gulp-ngmin - Make angular code friendly to minification
gulp-angular-htmlify - Make angular code valid html5

Pre-Filling PDF Form Templates in Ruby-on-Rails with PDFtk

2014-01-31T00:00:00+00:00

In a recent post, I talked about how to generate PDF reports in Rails using Prawn. This approach is great for generating PDF’s with lots of data tables and other variable-length content. But an alternative situation is when you already have a template authored in an application such as Adobe Acrobat and you want to populate it with data from your database. This makes it more difficult to insert variable-length content, but on the plus side, you no longer need to worry about the layout of the document.

While there are a number of libraries out there that can perform PDF manipulation, the one I have found to work best is PDFtk. There is a GUI version, but you’ll want the command line version, which is available in most package managers. ¹ This library is free for personal use, but requires a license if used in production.

PDFtk is a non-ruby command line tool and while it works great on its own in that context, it will be much easier if we use a ruby wrapper, so go ahead and add the pdf-forms gem to your project.

For this example, I’ve provided a really simple PDF form that I created in Adobe Acrobat ². You can download it here and add it to your project (I put mine in lib/pdf_templates). There are plenty of other resources out there on creating PDF forms, so I won’t go over that, but make sure you take note of the names of the fields. If you are starting with a template created by someone else, you’ll still want to open it up in Adobe Acrobat (or a similar app) to reference the names of the form fields. ³. The pdf-forms gem has a command for viewing the names, but I found that it didn’t always work.

Next, let’s get to the coding. Just as in my post on generating pdfs with Prawn, I like to represent each pdf document as a ruby class. But first let’s create a base class that takes care of the common functionality. So create a file called fillablepdfform.rb. In my rails app, I placed it in app/pdfs. ⁴. Here’s how my base class turned out:

class FillablePdfForm

  attr_writer :template_path
  attr_reader :attributes

  def initialize
    fill_out
  end

  def export(output_file_path=nil)
    output_path = output_file_path || "#{Rails.root}/tmp/pdfs/#{SecureRandom.uuid}.pdf" # make sure tmp/pdfs exists
    pdftk.fill_form template_path, output_path, attributes
    output_path
  end

  def get_field_names 
    pdftk.get_field_names template_path
  end

  def template_path
    @template_path ||= "#{Rails.root}/lib/pdf_templates/#{self.class.name.gsub('Pdf', '').underscore}.pdf" # makes assumption about template file path unless otherwise specified
  end

  protected

  def attributes
    @attributes ||= {}
  end

  def fill(key, value)
    attributes[key.to_s] = value
  end

  def pdftk
    @pdftk ||= PdfForms.new(ENV['PDFTK_PATH'] || '/usr/local/bin/pdftk') # On my Mac, the location of pdftk was different than on my linux server.
  end

  def fill_out
    raise 'Must be overridden by child class'
  end

end

And now I can keep my actual test pdf form class short and sweet. The fill_out method is all that’s required.

class TestPdfForm < FillablePdfForm

  def initialize(user)
    @user = user
    super()
  end

  protected

  def fill_out
    fill :date, Date.today.to_s
    [:first_name, :last_name, :address, :address_2, :city, :state, :zip_code].each do |field|
      fill field, @user.send(field)
    end
    fill :age, case @user.age
      when nil then nil
      when 0..17 then '0_17'
      when 18..34 then '18_34'
      when 35..54 then '35_54'
      else '55_plus'
    end
    fill :comments, "Hello, World"
  end
end

And my controller might look something like this:

class UsersController < ApplicationController
  def show
    user = User.find(params[:id])
    respond_to do |format|
      format.pdf { send_file TestPdfForm.new(user).export, type: 'application/pdf' }
    end
  end
end

And that’s all you need! The generated form will be both readable and writable in Adobe Reader and Mac Preview. So if you need the user to fill out a few additional fields, they can do so. But if you don’t want this, simply mark the fields in your template as read-only. So if your template isn’t a “form” but you just want to merge some data into a document, this is still a great way to do it.

From there, creating additional forms is extremely easy. The only difficulty I ever encounter is in figuring out the proper field names for templates I didn’t create, but this is still fairly trivial.

If you have any questions, send them to me on Twitter.

While PDFtk is free for personal use, it does require a license in production. ↩
There are many lower-cost and free alternatives to Adobe Acrobat, but I don’t have any experience with them, so I won’t make any recommendations. ↩
If Acrobat shows you an error message that something like “This form cannot be edited in Acrobat. Please use Adobe LiveCycle Designer to edit this form”, then you’ll either need to either get a version of the PDF that doesn’t have these permissions turned on or you’ll need to export it the document as a new pdf, and then re-import it into Acrobat and lay out the form fields yourself. ↩
You may need to restart your dev server to make sure it picks up changes in this new folder. ↩

A Better Onboarding Experience in your Angular.js Application

2014-01-22T00:00:00+00:00

“Onboarding” is one of those things we sometimes forget about when developing an application, but it really deserves more attention. Showing the user how to use your app can be critical in retaining them. Some people might say that if you need onboarding, your app just needs to have a better UX, but I don’t think this is practical in all situations, particularly complex business applications.

For my current Angular app, I wanted a nice way to point out and explain the various features of the application right after signup. I looked through a few javascript plugins such as Tourist.js, Guiders.js, and a few others, but none seemed to work well with angular, so I decided to write my own, which I’m calling ngOnboarding.

The library consists of a directive (<onboarding-popover>) that requires an array of ‘steps’ to be setup in your controller. Each step represents a popover element that may optionally point to an element on the screeen. Your step configuration might look something like this:

$scope.onboardingSteps = [
  {
    title: "Welcome!",
    position: "centered",
    description: "Welcome to my app!",
    width: 300
  },
  {
    title: "Account Setup",
    position: "right",
    description: "This is the form for configuring your account.",
    attachTo: "#account_form",
    position: "bottom"
  }
];

Unfortunately, I had to make a design decisions that I don’t particularly like, which is forcing you to reference CSS selectors in the controller. This is generally frowned upon in Angular, but I don’t see a another way to support anchoring the popovers to elements on the page. If you can think of a better way to implement this, I’d love to hear it.

While it’s still in development and not well-tested, it seems to work pretty well, so check it out!

Generate Clean, Testable PDF Reports in Ruby/Rails with Prawn

2014-01-14T00:00:00+00:00

I generally hate PDF’s. The file format is complex and designed to mimic physical paper documents, which really has little to do with the web. But unfortunately, PDF’s are still very common and often expected, particularly when working on businesses applications. I have a legacy ruby-on-rails application with a number of PDF reports and I recently took the time to refactor them in a clean and testable manner. Here’s how I went about that process:

The Report Requirements

For my project, most of my PDF reports consisted of primarily large tables of data along with a few other random pieces of data and information. Here is a screenshot of one of the simpler ones:

Prawn

The reports I’m working on have been done with the Prawn library from the beginning. This is the only direct PDF generation ruby library that I’m aware of. The early days of Prawn were a bit shaky and it didn’t support a number of features you’d expect, but the more recent versions are quite robust. And their self-documenting manual is generated using the library itself and is quite useful.

Why not use an HTML-to-PDF Library?

There are several libraries available that let you write your PDF’s in HTML and CSS, including PDFKit and wicked_pdf. Both of these use wkhtmltopdf behind the scenes. While this may suit your needs, I found that creating reports in this manner made it more difficult to manage the layout of the document, particularly when there was more than a single page.

Keep it Dry

The first thing I noticed was how much was shared between the reports. Each had either identical or very similar headers and footers, along with a number of often-repeated design paradigms that could be easily encapsulated into helper methods and constants. So I created a parent class that all my PDF reports would inherit from. It looked something like this:


class PdfReport < Prawn::Document

  # Often-Used Constants
  TABLE_ROW_COLORS = ["FFFFFF","DDDDDD"]
  TABLE_FONT_SIZE = 9
  TABLE_BORDER_STYLE = :grid

  def initialize(default_prawn_options={})
    super(default_prawn_options)
    font_size 10
  end

  def header(title=nil)
    image "#{Rails.root}/public/logo.png", height: 30
    text "My Organization", size: 18, style: :bold, align: :center
    if title
      text title, size: 14, style: :bold_italic, align: :center
    end
  end

  def footer
    # ...
  end

  # ... More helpers
end

PDF Report Classes

Then I built my actual reports, each of which is its own class that inherits from the above PdfReport. I broke up each section of the pdf into its own private method in order to make the code easy to follow.


class EventSummaryReportPdf < PdfReport
  TABLE_WIDTHS = [20, 100, 30, 60]
  TABLE_HEADERS = ["ID", "Name", "Date", "User"]

  def initialize(events=[])
    super()
    @events = events

    header 'Event Summary Report'
    display_event_table
    footer
  end

  private

  def display_event_table
    if table_data.empty?
      text "No Events Found"
    else
      table table_data,
        headers: TABLE_HEADERS,
        column_widths: TABLE_WIDTHS,
        row_colors: TABLE_ROW_COLORS,
        font_size: TABLE_FONT_SIZE
    end
  end

  def table_data
    @table_data ||= @events.map { |e| [e.id, e.name, e.created_at.strftime("%m/%d/%y"), e.created_by.try(:full_name)] }
  end

end

This PDF report could then be generated by the following:

# events = [...]
pdf = EventSummaryReportPdf.new(events)
pdf.render_file "/tmp/my_report.pdf"

Integration with Rails

As Ryan Bates suggested in his excellent screencast, I created a separate app/pdfs folder where I placed all my reports. Then in my controller, I would have the following action method:

def summary_report
  events = Event.all
  pdf = EventSummaryReportPdf.new(events)
  respond_to do |format|
    format.pdf { send_data pdf.render, filename: 'summary_report.pdf', type: 'application/pdf', disposition: 'inline' }
  end
end

Testing

What’s great about this solution is how well it lends itself to testing. By using the pdf-reader gem, we can convert the renderred PDF into a string and assert that the proper content is included. So a couple example tests (using Rspec) might look something like this:

describe EventSummaryReportPdf do
  context 'Given an array containing a single event' do
    let(:events) { [{id: 10, name: "Company Meeting", created_at: 1.day.ago, created_by: {full_name: 'John Doe'}] }
    context 'The rendered pdf content' do
      let(:pdf) { EventSummaryReportPdf.new(events) }
      let(:pdf_content) { PDF::Reader.new(StringIO.new(pdf.render)).page(1).to_s }

      it 'contains the name of the event' do
        expect(pdf_content).to include('Company Meeting')
      end
      it 'contains the full name of the user' do
        expect(pdf_content).to include('John Doe')
      end
    end
  end
end

Conclusion

This makes the process of creating PDF documents a little less painful. For those of you who are HTML and CSS wizards, be prepared to get really frustrated by how hard it is to lay out your documents in code. But just be mindful of anything that can be encapsulated into a helper method for usage later.

This covers one type of PDF report generation that is often more appropriate for generating variable-length reports. In my next blog post, I’m going to go over the process of pre-filling PDF form documents with data from your application.

How to Create a Simple Modal Dialog Directive in Angular.js

2013-12-12T00:00:00+00:00

Modals are Easy

I’ve used a dozen or so modal / lightbox plugins over the years, almost exclusively jQuery-based. But you know what I didn’t realize until fairly recently? Modals are easy to build yourself from scratch. So let’s make one in the Angular fashion.

The Requirements

I want to be able to create a modal with the following HTML:

<modal-dialog show='modalShown' width='750px' height='90%'>
  <p>Modal Content Goes here<p>
</modal-dialog>

And I’d like it to have the following features:

Toggle it by setting a single $scope variable to true or false (above, the variable is modalShown)
Optionally specify the height and width as either a px or % value.
Overlay the rest of the screen
Close by either clicking an X in the corner or outside the dialog

The Directive Code

This is a fairly simple directive, with a link function that’s only a few lines long. The show: '=' in the isolated scope sets up a 2-way binding between the variable given to the show attribute and the show variable on our scope. Setting this to true or false will toggle our modal dialog. And we check for height and width attributes and, if set, give the modal dialog an inline style. Finally, the hideModal() method simply sets the show variable to false.

app.directive('modalDialog', function() {
  return {
    restrict: 'E',
    scope: {
      show: '='
    },
    replace: true, // Replace with the template below
    transclude: true, // we want to insert custom content inside the directive
    link: function(scope, element, attrs) {
      scope.dialogStyle = {};
      if (attrs.width)
        scope.dialogStyle.width = attrs.width;
      if (attrs.height)
        scope.dialogStyle.height = attrs.height;
      scope.hideModal = function() {
        scope.show = false;
      };
    },
    template: '...' // See below
  };
});

The Template

The template is also fairly basic. Note that the ng-transclude indicates where your modal content will go. And also note the use of ng-style, which will translate a javascript object into an inline style.

<div class='ng-modal' ng-show='show'>
  <div class='ng-modal-overlay' ng-click='hideModal()'></div>
  <div class='ng-modal-dialog' ng-style='dialogStyle'>
    <div class='ng-modal-close' ng-click='hideModal()'>X</div>
    <div class='ng-modal-dialog-content' ng-transclude></div>
  </div>
</div>

The CSS

I’m not going to spend any time going over this, but I will say that the following will only work in modern browsers (specifically the translate function). If you need <= IE9 support, you’ll need center the dialog using a different method.

.ng-modal-overlay {
  /* A dark translucent div that covers the whole screen */
  position:absolute;
  z-index:9999;
  top:0;
  left:0;
  width:100%;
  height:100%;
  background-color:#000000;
  opacity: 0.8;
}
.ng-modal-dialog {
  /* A centered div above the overlay with a box shadow. */
  z-index:10000;
  position: absolute;
  width: 50%; /* Default */

  /* Center the dialog */
  top: 50%;
  left: 50%;
  transform: translate(-50%, -50%);
  -webkit-transform: translate(-50%, -50%);
  -moz-transform: translate(-50%, -50%);

  background-color: #fff;
  box-shadow: 4px 4px 80px #000;
}
.ng-modal-dialog-content {
  padding:10px;
  text-align: left;
}
.ng-modal-close {
  position: absolute;
  top: 3px;
  right: 5px;
  padding: 5px;
  cursor: pointer;
  font-size: 120%;
  display: inline-block;
  font-weight: bold;
  font-family: 'arial', 'sans-serif';
}

Finally, to put it all together, you’ll need to add a small bit of code to your HTML and controller.

<button ng-click='toggleModal()'>Open Modal Dialog</button>
<modal-dialog show='modalShown' width='750px' height='60%'>
  <p>Modal Content Goes here<p>
</modal-dialog>

app.controller('MyCtrl', function($scope) {
  $scope.modalShown = false;
  $scope.toggleModal = function() {
    $scope.modalShown = !$scope.modalShown;
  };
});

All Together

And that’s it! I put all the code together in a demo on JSBin. Check it out. And I’ve put a slightly more polished and configurable version of this directive up on Github.

A Better Date Picker in Angular.js

2013-12-01T00:00:00+00:00

UPDATE (March 14th, 2015)

When I first wrote this library, I didn’t have a great understanding of the ngModelController API, nor good directive design. So I wouldn’t recommend this library anymore. I started on a replacement library here, though it’s not quite ready for production use.

I wasn’t particularly happy with any of the datepicker directives out there for Angular.js, so I decided to build one myself. I did it out of a need on my current project but also because I wanted to learn the ins and outs of directives. You can find the library on Github.

Requirements:

Easy to use via the keyboard. I hate when I’m using a form-centric application and there’s one particular field that I can’t just tab through.
No dependencies (besides angular). Many of the existing datepicker directives are just jQuery widgets that are made to work with Angular. I wanted to build something from scrath in the “angular way”.
Very configurable. If it’s not totally required, make it optional.
Lightweight styling that can be easily overridden. Too many front-end libraries assume you’re using bootstrap or a particular icon font. I actually am using bootstrap for my project, but I don’t want it to be forced on anyone.

The End Result:

After a few hours hacking here and there for a couple weeks, I have something fairly stable that I’m calling ngQuickDate. It is built with Coffeescript, meets all my requirements, is fairly well tested using jasmine, and works pretty damn well if you ask me. Unfortunately, there were quite a few breaking changes in the recent 1.2 release of Angular, so currently it only works with 1.0.8. I’ll be releasing a 1.2 compatible version shortly.

Lessons Learned:

If you really want to understand the amazing directive system in Angular, building a datepicker or another similarly-complex UI widget is a great way to go about it. I had to go through a number of iterations before it felt right, but I learned a lot in the process. A few things to keep in mind:

Learn what’s already built into angular before you pull in any 3rd-party libraries. For example, I didn’t realize at first that I could use filters in my javascript code (as opposed to just in templates), so I was using another library to format dates.
Take the time to provide some decent configuration for your directive. Angular provides a nice way to set the original default settings using a ‘provider’.
Make 3rd-party libraries optional by providing basic functionality without them, and extended functionality with them. In ngQuickDate, you can configure it to work with a library like Sugar.js for enhanced date parsing, but it’s not required.
Use SMACSS or a similarly modular system for writing your directive’s CSS. By doing this, you’re much less likely to use conflicting class names, you’ll write more efficient CSS, and make it easier to re-style.
Stick to the tools you know and love if it will help your project. I started out with the intention of doing it in plain Javascript and CSS so I wouldn’t turn off any developers out there unfamiliar with Coffeescript or any of the CSS pre-processors. But writing Coffeescript is just so much more fun the end-result is much more succinct and readable.

How to Auto-Save your model in Angular.js using $watch and a Debounce function.

2013-10-30T00:00:00+00:00

The Problem

Currently, I’m working on an Angular app that is very form-centric. Fields and fields and more fields. I want to make the form-filling process as quick and painless as possible, so I’m trying to implement auto-save.

Update (March 19th, 2014)

I’ve done quite a bit more auto-saving on my current project and I’ve updated my post with some slightly better methods. It also now has a solution for when you are trying to auto-save multiple items in an array. I combined a lot of the info below into this live example.

First Attempt

My first attempt at an auto-save solution (while still being very new to Angular) was a directive that, based on the type of element, waited for either a change or blur event to occur and communicated to the controller (via a service) that it was time to save the model.

<input type='text' ng-model='myModel.field1' auto-save />
<select ng-model='myModel.field2' auto-save >...</select>

A simpler version of this method might look something like this:

<input type='text' ng-model='myModel.field1' ng-blur='save()' />
<select ng-model='myModel.field2' ng-change='save()' >...</select>

There are a few problems with this method:

I have to add these extra attributes to each and every input field. If I happen to forget one, my user may lose their data since there aren’t any explicit ‘Save’ buttons.
It won’t auto-save until the user changes the focus of the field. This is particularly problematic with <textarea> fields, where the user may type for long periods of time before changing focus.
I’d much rather my view not know anything about when my model is or isn’t being saved to the server.

New Solution: $watch and debounce

My new solution uses the $watch method that Angular provides for watching for changes to scope variables. I don’t want to make requests to the server with every keystroke, so I’ll use a simple debounce function (using Angular’s $timeout service) to limit my requests to happening every few seconds.

To implement this solution, there is nothing to add to your view. But in the controller, you’ll need to inject $timeout and write a couple $watch statement. I added a watch statement for each individual attribute of the model, but you could also do a deep watch of the entire model. This is slightly more expensive performance-wise.

<input type='text' ng-model='myModel.field1' />
<select ng-model='myModel.field2'>...</select>

app.controller('myCtrl', function($scope, $timeout) {
  $scope.myModel = {};
  var timeout = null;
  var saveUpdates = function() {
    // .... save data to server
  };
  var debounceSaveUpdates = function(newVal, oldVal) {
    if (newVal != oldVal) {
      if (timeout) {
        $timeout.cancel(timeout)
      }
      timeout = $timeout(saveUpdates, 1000);  // 1000 = 1 second
    }
  };
  $scope.$watch('myModel.field1', debounceSaveUpdates)
  $scope.$watch('myModel.field2', debounceSaveUpdates)
});

Potential Gotcha #1: Validation

Angular.js doesn’t provide any sort of model validation (or any model-related code at all) and instead recommends that you validate the form using a combination of HTML5 validation and a few built in directives. Angular includes a way to access our form and its $valid attribute. First, we need to wrap our fields in a <form> tag with a name attribute and also make our fields required.

<form name='myForm'>
  <input type='text' ng-model='myModel.field1' required />
  <select ng-model='myModel.field2' required>...</select> 
</form>

Next, we need to update our controller a bit to check the validity of our form.


var saveUpdates = function() {
  if ($scope.myForm.$valid) {
    // .... save data to server
  }
};

If you need more complex validators, you’ll need to create custom directives that make use of the $setValidity method.

Potential Gotcha #2: Preventing Double-Saves on Create

One problem I ran into was that when I auto-saved a brand new object was that the object was replaced with the version from the server, causing the $watch function to be triggered again. The result was that my object was immediately saved a second time, unnecessarily. The solution to this is fairly simple: just set a saveInProgress flag so that it never starts another save before the previous one finishes. This will also prevent a double-save caused by a save call that is slower than the timeout on your debounce function. It might look something like this:

var saveInProgress = false;
var saveFinished = function() { saveInProgress = false; };
var saveUpdates = function() {
  if ($scope.myForm.$valid) {
    saveInProgress = true;
    saveFunction().finally(saveFinished); // The finally method runs regarless of whether the save was successful or not.
  }
};

A related and much harder problem is how to resolve changes to the model that happen during the round-trip of the save. I recently had a discussion on Twitter about this, but I think it really comes down to designing your UX to discourage or prevent your user from making changes to the model while still waiting on that first POST creation request. If you also replace your model with the server’s version on subsequent updates (which is generally not recommended), the problem gets a little trickier.

Potential Gotcha #3: Auto-Saving individual items in an array

Another issue that you’ll often run into is when you have an array of objects, perhaps in a grid interface. While angular does provide a $watchCollection method, it only does a shallow watch on the array as a whole and won’t tell you which item was changed.

Instead, a better solution is to wrap the fields of each individual item inside a child controller or directive. Here is a live example of how that would work.

And that’s it! This is an extremely simple example, so if you have any questions or comments, give me a shout out on Twitter.

Adam Albrecht

Home Cooked Apps

Click Publish

Add a Little Safety to your Elixir Structs with TypedStruct

Upcoming Phoenix Authentication Solution

JavaScript Sprinkles with AlpineJS

Enable Spell Checking in Vim for Markdown and Git Commit Messages

Dark Mode and other site updates

Quickly Convert 4 Spaces (or Tabs) to 2 spaces in Vim

Get the Previous Expression Value in IEx

Ruby Symbol and String Array Shorthand

Symbol Array Shorthand:

String Array Shorthand:

Running Elixir tests in VSCode

SSH Tunnels into Production Rails Database

Rails presence method

VSCode + ElixirLS = 👍👍

Netlify Analytics First Impressions

Pros:

Server Side

Privacy Centric

Cons:

Server Side

Extremely barebones

Expensive!

Conclusion:

TIL: Pass in an ActiveRecord Object to a where string

Lookup IP Address & Location via the Command Line

Website Revamp! And introduction to my Work Journal.

Run your Ruby tests quickly and easily using Vim and Tmux

Authentication with JSON Web Tokens using Rails and React / Flux

Server Side

Client Side

Auth API Wrapper

Session Managment using Flux

Login Form Component

Conclusion

How to Replace the Angular Stack with React plus a few NPM modules

Routing

Promises

HTTP Requests

Modules / Dependency Injection

Unit Testing & Mocking

Conclusion

Authenticating your Angular / Rails App with JSON Web Tokens

Overview

Client/Server Data Flow

Server-Side Code

Client Side Code

Authorization with Angular.js and UI-Router

Building your Angular app with Gulp.js

The Original Gruntfile

Simple Gulpfile

Angular Extras in Gulp

More Resources

Documentation:

Common Gulp Utilities:

Common Gulp Pre-Processors

Minification Plugins

Angular Helper Plugins

Pre-Filling PDF Form Templates in Ruby-on-Rails with PDFtk

A Better Onboarding Experience in your Angular.js Application

Generate Clean, Testable PDF Reports in Ruby/Rails with Prawn

The Report Requirements

Prawn

Why not use an HTML-to-PDF Library?

Keep it Dry

PDF Report Classes

Integration with Rails

Testing

Conclusion

How to Create a Simple Modal Dialog Directive in Angular.js

Modals are Easy

The Requirements

The Directive Code

The Template

The CSS

Triggering the Modal

All Together

A Better Date Picker in Angular.js