no.lol

This Time Is Different

Tue, 12 May 2020 00:17:26 GMT

This time is different. “Clean slate. Solid foundations. This time I will build things the right way.”

The Life of a Software Engineer, by Manu Cornet

I used to be obsessed with “best practices”. I wanted to write code that would stand the test of time. Code that was objectively ideal. Everything had to be functional, pure, composable, and perfectly extensible. The fact that my programming idols on Twitter said it was good was convincing enough. Who was I to question them? There was a sense I had that if I wrote it well enough and adopted the right patterns and libraries, that my project would be set for life.

At one point I even gathered enough hubris to speak about writing Idiomatic Code, lecturing others on ways they could future proof their codebases today. Embarassingly for me, these solutions never landed in the next version of the framework. Idiomatic indeed.

Best practice today, anti-pattern tomorrow

As I gained experience working on more projects, I started to question the dogma I accepted without question. If I had to identify the turning point, it was when I first started learning a new programming language, Elixir. Up to that point, Ruby and JavaScript were the tools I knew best. It turns out that there’s truth behind Maslow’s Hammer—“I suppose it is tempting, if the only tool you have is a hammer, to treat everything as if it were a nail.” In the same way, when you learn new concepts like functional programming for the first time, it’s only natural to start seeing patterns in your codebase that could be cleaned up and optimized with your newfound knowledge. The same could be said for PRs on GitHub that “refactor” function declarations into arrow function expressions. It’s not always better because it’s shorter!

Learning a new language that was unlike anything I had used before was humbling. I struggled for hours trying to understand pattern matching. Variable declarations are one of the first things you learn as a total beginner in any programming language. Yet here I was struggling to understand it, despite having done this for a few years.

It forced me to expand my perspective on different techniques and an appreciation for why they were used. Almost everything has a use. Finding a satisfying solution that is always better in 100% of use cases is exceedingly rare. As much as I enjoyed the functional nature of Elixir and recursing everywhere, I realized that some things are more efficiently solved with a good old for loop. Both techniques have their place.

Great post about learning new mental models via new languages. When I started my career I learned Ruby and JS. For a while, those idioms shaped the way I thought about code. When I learned Elixir and about the Erlang VM (BEAM), everything I knew about backends and APIs changed https://t.co/cKOMNfF6Ua
— lauren (@poteto) May 1, 2020

I’ve picked up more languages and tools since then, but the humbling lessons don’t stop. Paradoxically, the more I know, the less I understand.

We often look to proxies like Twitter follower counts, stars on GitHub, and loudness of voice to tell us what we should do next. That’s fair—sometimes, you just want to get your job done. Software is still a relatively young industry, and it seems to change rapidly. That often is overwhelming. But I’ve learned that starting from the default of thinking that this must be good because someone famous said so is a flawed foundation. Consider the problem you’re trying to solve, the opportunity cost of going with this solution instead of another, and the tradeoffs your team is comfortable making. Dealing with ambiguity and making tradeoffs is part of the job. A worse trap to fall into is taking best practices at face value and applying that everywhere across your code without further consideration.

More importantly, realize that whatever you decide to go with today will likely change in the long term. If your project even lasts that long. And that’s okay.

This time is no different

I learn from many random sources on the internet. One source I find myself going back to often are videos about cooking. There’s something magical about watching people make things. And I like to eat.

When I first watched Jiro Dreams of Sushi almost 10 years ago, I didn’t understand what drove Ono. His obsession with perfection seemed pointless. Surely at some point, after decades of making sushi, there would be nothing left to perfect.

I’ve come to realize that perfection is not a destination. It’s an incremental journey, process, or whatever you want to call it. Whether it’s today’s project, or a project I’ll work on next year, every piece of software is the same, only different. Put another way, something that works well on one project might not yield the same results in another.

Instead of seeing code as an unchanging structure, like a building, think of your software as a living thing. Every project changes and grows over time. The people who work on it come and go. The people who use your software also change. Like things that constantly change, software is never finished. It just gets released (hopefully continuously).

“We are simply never going to realize a state of software nirvana where everything is supremely satisfying. That’s an important emotional realization. The fundamental reward of an improvement process is the experience of betterment, not some mythical destination.” - Mark Slee

I suppose there’s a certain zen of software engineering that comes with experience that is hard to learn without the scars to prove it. So go forth, make those mistakes, and find peace with yourself. And the next time, it’ll be different :)

This blog post was inspired by this writing from Mark Slee. It was written 10 years ago, but it’s still excellent. Highly recommended.

Does It Spark Joy?

Mon, 17 Feb 2020 20:29:57 GMT

tl;dr This week, I’m resigning from Netflix to return to being a software engineer. I’ll announce where I’m moving to next month.

I remember the day vividly.

My skip (manager’s manager) sent us a last minute calendar invite, vaguely titled “Org Updates”. I was surprised, but also wasn’t. I was getting used to changes in a rapidly growing organization. It didn’t take a lot to figure out what was going on.

I looked at the invite list, and mentally calculated the delta between the org chart and the people invited. A couple of people I knew weren’t on it—most notably, my manager.

My manager was someone I looked up to. I still do. They were always honest with me, and gave me opportunities to stretch skills I didn’t know I had. They were the rare breed of manager who was able to align your personal growth with the goals of the company. I became a tech lead for the first time with their help. The news of their departure caught me by surprise, and I cried at work when I heard it. It’s difficult to find a manager that “gets it”, and I had just lost mine.

My skip and the VP Eng later pulled me aside for a chat. “Lauren, I know this news is hard for you. Your manager helped get this org get started, and …[other things that aren’t relevant to the story]. I know we’ve had a couple of conversations about leadership and management recently. I think you’re ready to be the engineering manager of this team.”

It was true—I was very curious about management. I pestered other managers to tell me everything they knew about leadership, and to tell me stories about what the job was like. I spoke to anyone who would spare me a minute. I eagerly read all the articles and blog posts, and put recommended books on my reading list. I had even volunteered to help my manager with hiring and to put together a take home exercise. But I was just doing research. I hadn’t planned on being a manager at this very early point of my career, which had really just started. At that point, I was about 5 years into working professionally as a software engineer after 2 years working on a failed startup.

To be honest, I don’t remember what exactly my skip and their manager said that day. I was trying to process my emotions from the days’ news, so I wasn’t listening to most of what they said. I couldn’t. Even though they tried to tell me that I was ready, I didn’t feel it. I didn’t think I could do it.

I ended up taking the job a couple of days later. I realized it was a Type 2 decision, so there was no point agonizing over making a perfect decision. One guiding principle that has shaped my career is: do things that scare you. Fears tend to disguise opportunities for personal growth. Switching roles to be a manager was completely uncharted territory for me. I was terrified, but whatever happened, I knew I would be learning and growing. I also had a backup plan: I could go back to being an engineer if I didn’t let my skills atrophy too much.

Does it spark joy?

When I took the job, I promised myself two things:

I would always do my best for the company—no matter how difficult it got, how many hard conversations I’d have to have, how many people I needed to hire, and no matter how insurmountable the challenge seemed—I told myself I’d stick it out and always put in 100%.
I would reevaluate every year whether it was still my dream role. If it wasn’t, I had to go back and not be stuck in a job that I didn’t love.

Early last year, I told my new manager what I just told you. Their response was classic. They asked me in return, “what brings you ultimate joy?”. I left our 1:1 feeling deeply introspective, but with more questions than I had answers. I thought I was going to get actionable advice. Instead, I felt like I had gone up the mountain to see the oracle, and returned with a riddle.

I lay in bed that night unable to sleep. I was thinking about that question and reflecting on my past year. Life as a manager had been difficult, lonely, rewarding, and everything in between. What I liked about management was the same thing that got me interested in it in the first place—it’s all about the people. I loved fully owning the composition of my team, coaching my team into wild success at Netflix, and creating an environment where they can thrive. I certainly had lots of satisfaction from doing these things and I know they were very impactful. But did it bring me joy?

My thoughts went back further. My programming career had started from a pivotal point—my stepdad handing me a CD-R containing a pirated copy of Macromedia Fireworks when I was about 13. Don’t worry, I got Photoshop a little bit after, and paid for it too :) Armed with an internet connection and infinite curiosity, I came across a local community of web and graphic designers hanging out on a web-based forum. This was the early 2000s, when forums built with phpBB were all the rage. I hung out with them on IRC and we said silly internet things to each other like “roflcopter”. We thought we were the shit, but it was just weird.

I loved it.

Through trial and error, view source, endless tutorials, and a ton of patience, I absorbed everything I could about design and web development. My grades suffered, but I learned more than I ever did in class. I had never been so intrinsically motivated 😂. Later, I worked freelance and earned some pocket money designing websites for schools and small local businesses. I have fond memories of abusing lens flares; writing unintelligible JavaScript; creating horrible Flash animations; using HTML <table>s, sliced images and spacer.gif for layouts.

Because I neglected school so much, I had a difficult time after high school. I grew up in Singapore, a country obsessed with academic credentials. I didn’t do well enough to go anywhere. As a last resort, I applied to an art and design polytechnic on special consideration. My time spent learning Photoshop and web design as a young teenager helped me put together a portfolio. I still remember feeling so shocked that I managed to trick them into accepting me.

I realized that what I miss most is being a maker. It’s hard to describe what being a maker is, but I can describe what it feels like. It’s that feeling you get when you turn a blank canvas or empty document into something. Whether it’s a painting, a sculpture, code, it all still feels like magic. If you’re as fortunate as I am, you might know this feeling too. It’s powerful stuff. When I was working as an engineer, going into work everyday made me giddy with excitement. It didn’t feel like work. I’m getting paid to do my hobby! As a manager, I still made things in my spare time, but it wasn’t quite the same.

The riddle-like advice I had gotten was spot on. Only I could answer this question for myself. And now I had my answer.

What’s next

This week, I’m resigning from Netflix to return to being a software engineer. I’ll announce where I’m moving to next month. Leaving somewhere you’ve worked for 4 years is scary, but you know my opinions on fear.

After 2 challenging and rewarding years as an engineering manager, one of the most valuable lessons I’ve learned is that you can be both an individual contributor and a leader. Some of the most effective ICs I’ve worked with do this incredibly well and know that you don’t need to be a manager to be a leader. I’ve distilled a few of these things down into personal engineering leadership principles that I plan to evolve and bring along with me into my next adventure. I’ll write about this topic more in a future blog post.

I’m excited that I’ve found an opportunity that aligns with my personal growth goals, and humbled that I’ll get to explore this with an incredible group of kind, smart, and thoughtful human beings. I’ll share more details next month on Twitter.

I leave you with these questions from @millie’s wonderful slide deck on what to do with your life:

If you find it hard to wake up excited about going to work in the mornings, ask yourself why
If working at your current company is not aligned with your long-term goals or values, consider making a move
If you’ve never thought about where you’d like to be in three years, sit down and think about it

Keep doing things that scare you.

Type Narrowing in TypeScript

Sat, 28 Dec 2019 04:15:24 GMT

One of my 2020 resolutions is to learn how to create my own programming language, along with an interpreter and compiler for it. I’m writing the interpreter and compiler in TypeScript. My eventual goal is to compile it into wasm, and introduce some fun language features like pattern matching, the pipe |> operator from F#/Elixir, and other fun stuff I haven’t yet thought about.

As of time of writing, I have mostly completed the lexer and parser for my interpreter and am about to jump into evaluation. I stream on Twitch when I work on it (usually weekends PST), so check in if you’re interested in watching!

This blog post is to share a TypeScript tip I’ve picked up while creating this language: type narrowing.

Being precise helps TypeScript help you

When lexing my language, I create tokens that represent the various language features you might use in your program: defining functions and variables, using infix operators like + in x + y, conditional logic, and so on. I created a Token type that represents a simple data structure representing my tokens. Each token has a type property that comes from an enum that represents the various syntax of my language:

token.ts

export type LiteralType = string;
export type Token = {
  type: TokenType;
  literal: LiteralType;
};
export const enum TokenType {
  ILLEGAL = 'ILLEGAL',
  EOF = 'EOF',

  // Identifiers + Literals
  IDENT = 'IDENT',
  INT = 'INT',

  // Operators
  ASSIGN = '=',
  PLUS = '+',
  MINUS = '-',
  BANG = '!',
  ASTERISK = '*',
  SLASH = '/',

  LT = '<',
  GT = '>',

  EQ = '==',
  NOT_EQ = '!=',

  // Delimiters
  COMMA = ',',
  SEMICOLON = ';',

  LPAREN = '(',
  RPAREN = ')',
  LBRACE = '{',
  RBRACE = '}',

  // Keywords
  FUNCTION = 'FUNCTION',
  LET = 'LET',
  TRUE = 'TRUE',
  FALSE = 'FALSE',
  IF = 'IF',
  ELSE = 'ELSE',
  RETURN = 'RETURN',
}

As an example, here’s what my lexer tokenizes when it encounters this input:

let add = fn(x, y) {
  x + y;
};

[
  { type: TokenType.LET, literal: 'let' },
  { type: TokenType.IDENT, literal: 'add' },
  { type: TokenType.ASSIGN, literal: '=' },
  { type: TokenType.FUNCTION, literal: 'fn' },
  { type: TokenType.LPAREN, literal: '(' },
  { type: TokenType.IDENT, literal: 'x' },
  { type: TokenType.COMMA, literal: ',' },
  { type: TokenType.IDENT, literal: 'y' },
  { type: TokenType.RPAREN, literal: ')' },
  { type: TokenType.LBRACE, literal: '{' },
  { type: TokenType.IDENT, literal: 'x' },
  { type: TokenType.PLUS, literal: '+' },
  { type: TokenType.IDENT, literal: 'y' },
  { type: TokenType.SEMICOLON, literal: ';' },
  { type: TokenType.RBRACE, literal: '}' },
  { type: TokenType.SEMICOLON, literal: ';' },
  { type: TokenType.EOF, literal: '' },
];

These tokens are iterated on by my parser, which parses the tokens and creates an Abstract Syntax Tree (AST). As it encounters tokens of different types (used in different contexts), it recursively creates AST nodes that take into account operator precedence. Here’s an example of an AST node that represents a boolean literal:

ast/nodes/boolean-literal.ts

export type BooleanLiteralToken = {
  type: TokenType.TRUE | TokenType.FALSE;
  literal: LiteralType;
};

export default class BooleanLiteral implements Expression {
  constructor(public token: BooleanLiteralToken, public value: boolean) {}

  expressionNode() { /** snip **/ }
  tokenLiteral() {  /** snip **/ }
  toString() { /** snip **/ }
}

The nice thing about this code is that the TypeScript compiler prevents me from creating an instance of the BooleanLiteral AST node if the current token is not of type TRUE or FALSE. This makes intuitive sense as I’d never want to have a BooleanLiteral AST node created for the token type of SEMICOLON. You could say that the BooleanLiteral constructor accepts a narrower version of the type Token.

The set of Tokens includes 27 tokens, but there are only 2 types of BooleanLiteral tokens

The problem now is that as I iterate through all the tokens from our input, TypeScript has no way to tell what kind of Token we’re currently examining. In fact, it throws a compiler error. How can we tell TypeScript what kind of token we’ve encountered?

parser/prefix/parse-boolean-literal.ts

export default function parseBoolean(this: Parser): Expression {
  return new BooleanLiteral(this.currToken, /* ... */);
  //                        ^^^^^^^^^^^^^^
  // Argument of type 'Token' is not assignable to parameter of type
  // 'BooleanLiteralToken'.
  //   Types of property 'type' are incompatible.
  //     Type 'TokenType' is not assignable to type
  //     'TokenType.TRUE | TokenType.FALSE'.ts(2345)
}

Type narrowing with assertion functions

TypeScript 3.7 introduces a new feature: assertion functions. Like type guards, using an assertion function lets you reassure the compiler that you have a more precise type. It also captures a common pattern in JavaScript, where we assert on invariants that must hold true at runtime.

To assert that the current token that’s being examined when the parseBoolean function is called is either { type: TokenType.TRUE } or { type: TokenType.FALSE }, we can use an assertion function that both narrows the type as well as throws a helpful runtime error if it does encounter something it’s not expecting:

utils/assert-token-type.ts

export default function assertTokenType<T extends TokenType>(
  token: Token,
  ...assertedTokenTypes: T[]
): asserts token is { type: T; literal: LiteralType } {
  const satisfiesAssertion = assertedTokenTypes.some(
    type => type === token.type
  );
  if (!satisfiesAssertion) {
    throw new AssertionError({
      message: `Token type is not: ${assertedTokenTypes.join(' OR ')}`,
    });
  }
}

After using the above assertion, TypeScript now knows that this.currToken must be either a token of type TRUE or FALSE:

parser/prefix/parse-boolean-literal.ts

export default function parseBoolean(this: Parser): Expression {
  assertTokenType(this.currToken, TokenType.TRUE, TokenType.FALSE)
  return new BooleanLiteral(this.currToken, /* ... */);
  //                        ^^^^^^^^^^^^^^
  // (property) Parser.currToken: {
  //   type: TokenType.TRUE | TokenType.FALSE;
  //   literal: string;
  // }
}

And in the event that something goes awry at runtime, I can at least throw an assertion error to help me debug the issue.

Type narrowing with type guards

Another handy way to narrow a type is to use type guards.

Here’s a common util that I use to check if an object has a property defined:

utils/has-own-property.ts

export default function hasOwnProperty<T>(
  obj: T,
  key: PropertyKey
): key is keyof T {
  return Object.prototype.hasOwnProperty.call(obj, key);
}

For example, this allows me to narrow the broad ident type in the lookupIdentifier function from string (cardinality: ∞) to the union type of string literals (cardinality: 7) that encompass the keys in my KEYWORDS map:

token.ts

const KEYWORDS = {
  fn: TokenType.FUNCTION,
  let: TokenType.LET,
  true: TokenType.TRUE,
  false: TokenType.FALSE,
  if: TokenType.IF,
  else: TokenType.ELSE,
  return: TokenType.RETURN,
} as const;

export function lookupIdentifier(ident: string) {
  if (hasOwnProperty(KEYWORDS, ident)) {
    return KEYWORDS[ident];
    //              ^^^^^
    // (parameter) ident:
    //   | "fn"
    //   | "let"
    //   | "true"
    //   | "false"
    //   | "if"
    //   | "else"
    //   | "return"
  }
  return TokenType.IDENT;
}

TypeScript can even infer the return type from my function signature without the need for me to be explicit:

// inferred by TypeScript
function lookupIdentifier(
  ident: string
):
  | TokenType.IDENT
  | TokenType.FUNCTION
  | TokenType.LET
  | TokenType.TRUE
  | TokenType.FALSE
  | TokenType.IF
  | TokenType.ELSE
  | TokenType.RETURN;

Neat!

Conclusion

In addition to assertion functions and type guards, you can also narrow types using the in operator, typeof type guards, instanceof type guards, and if statements.

Type narrowing gives TypeScript more information about the type being narrowed, and allows the TypeScript compiler to be more helpful to you. When used responsibly, narrowing types can make your code easier to understand. However, it can also be easy to get carried away with making your types extremely precise. I speak about this in my talk at TSConf (recording, slides).

Knowing when this tool is valuable, and when its not is part of the fun, pragmatism, and challenge of programming. I leave you with this quote from a talk by Runar Bjarnason about constraints:

When we restrict what we can do, it’s easier to understand what we can do.

#2 Maximizing Success in Engineering Interviews

Mon, 25 Mar 2019 19:33:52 GMT

Here is today’s 1:1 topic — finding success in software engineering interviews. The person I spoke to is new to tech and has been feeling frustrated understanding how to maximize their chances of success. This is largely because they haven’t received much feedback on what to improve on post-interview.

Trying a little experiment: starting next Sat (03/09), I'll be doing one-on-one meetings with people from under-represented minorities who are interested in: career/manager/tech advice, feedback on conference proposals, and more!

💁🏻‍♀️ Go here to apply: https://t.co/O2ve1Lp0pl
— lauren (@poteto) March 2, 2019

I honestly struggled putting together this post. There is much that isn’t right about the tech interview process, but I’ll save that for another time. This guide is for maximizing success in that interview that’s coming up for you next week.

Note: This post is based on my own experience, and is highly dependent on the company you’re interviewing with. I’ve tried to keep this as widely applicable as possible.

Before you begin

The thing that sucks the most about interviewing is that they are hugely one-sided in the power dynamic. As a candidate, you don’t really know what the company is looking for, and it’s easy to walk away from interviews feeling like you’re a failure. Remember: if you’re not finding success at interviews, it doesn’t mean that you’re a bad software engineer. Interviews are poor proxies for approximating the day-to-day work that software engineers actually do, and they often get it wrong (companies consider false negatives preferable to false positives).

Interviews generally suck and there’s no reason to feel bad about not being good at it. Learning to separate your value as engineer/self-worth from your interviewing skills will greatly help with your mental health. Please take the time for self-care!

What do interviewers look for?

Software engineering interviews generally try to answer these questions in different proportions. When you’re answering questions, keep these general areas in mind:

At a minimum, can this person do the job? If not, can we teach them?
Do they “raise the bar”? (i.e improve the team’s ability to execute)
Will they be successful in our team/company’s culture?

Depending on the needs of the company, the specifics may vary. These areas should be pretty common though. Think of an interview like giving an interactive presentation. It’s an artificial setting where you’re trying to communicate the value that you’ll bring to a team. Knowing what they’re looking for will help you adjust your approach and present your best self.

How do I demonstrate that I can do the job?

These are questions that involve your core skills as an engineer: problem solving, logic, breaking down large requirements into smaller tasks, knowledge/usage of specific technical concepts, and most importantly communication.

The kinds of questions you’ll get in this area depends on the role and company you’re applying for. Some places might place emphasis on CS fundamentals like data structures and algorithms. Others may focus on practical questions (ps: check out my hiring-without-whiteboards repo for a list of such companies). Regardless of what you get, the approach to answering them is mostly the same. The interviewer is trying to understand if you have the necessary skills to do the job, so help them out.

It’s important to remember that any question that involves technology can fall into this area. For example, even the question “Walk me through a particularly tricky project or challenge you tackled, and how you went about it.” has a technical component to it, although smaller than a fully technical question. Even seemingly “pure” technical questions will test you on important skills such as communication.

When you get a question in this area, take these approaches:

Work the question

For technical questions, this usually means starting with the simplest approach. The interviewer will then expand the scope of the question by asking you additional questions that make it more complex. For questions such as the “tricky project” one, start high level, then go into more details. For example: “One of the most challenging projects I worked on was Project Donut. The requirements were confusing, and we had to implement a complex data-driven UI that had a lot of perf constraints. To be specific, I had to work closely with our PM to clarify what the requirements were. They were new to the company and didn’t have a lot of context about the users we were trying to help. […] We first tried doing X to render all the items on screen, but this turned out to cause a lot of jank when scrolling. We then tried doing Y which […]”

What level of technical detail would they like you to go to? Will this list contain only integers? Would they prefer you spoke about a technically challenging project, or an organizationally challenging project? Asking for context will help you understand what the interviewer is looking for, and reduce the amount of guesswork you have to do.

Even if the interviewer is technical, explain what you’re doing and why. Don’t assume that they already know what it is. If you’re unsure, you can always ask if they would like you to explain something.

Throughout the interview, your interviewer may share feedback with you. If they’re suggesting something, go with it! It’s very rare that interviewers will try to mislead you or throw you off. If they suggest something, it’s usually because they’re trying to help.

Compare the tradeoffs

There are always pros and cons to every approach. Be prepared to talk about what you gain and lose from either. Why did you choose X over Y? Which would you recommend given the context of the problem? If you were to revisit this challenge again, what would you do differently?

Be honest

This one is arguably the most important. Just because you don’t know something doesn’t mean you’re not qualified for the job. How many super senior engineers still need to google stuff? 🙌🏻 Be honest if you aren’t familiar with a concept, don’t try to fake it because it’s easy to spot someone who doesn’t know what they’re talking about. This isn’t to say that you shouldn’t attempt the question, but set the right expectations before you do.

Do I raise the bar?

This area is much more subjective. There aren’t any specific questions that interviewers will ask you. It depends on the team and what they’re looking for. How you can show this is mostly about how you answer their questions in both technical and cultural rounds. One way to suss this out is to ask your hiring manager in the first few screens if there is anything specific they’re looking for that would make someone successful in this role. For example, they might say that they need someone with distributed systems expertise, or someone who can lead a project. You can use this information to adjust your approach in answering questions.

If you don’t get a specific answer, you can still tell based on the kinds of questions they ask you. If they ask you very specific questions about certain technologies or paradigms, you can probably guess that that is a skill they’re looking for. If the questions are pretty generic, they might not know what they’re looking for. In these kinds of interviews, try injecting bits of your strengths into every question. Even if you’re answering a technical question, you can add more information. For example, “if this were a real world problem, I would spend some time with the PM and designer to better understand what the user experience should be. Even though we could put hundreds of thousands of items on screen, it might not be the best experience for our users.” or “when we tried this approach, it improved the performance of our app by 20%. There was actually more performance I thought we could squeeze out by doing X and Y, but after speaking with my manager and considering the constraints of the business, I decided to put that on the backlog and tackle more pressing needs first.”

Being successful in a company’s culture

Another way of looking at a company is that it’s a group of people. The way groups of people interact, what they consider acceptable, and what they don’t, defines the culture of that group. Most companies these days have cultural values on their jobs pages (for example, check out Netflix’s culture memo). The company you’re applying for will most likely have one of their own as well. The point here is to do your homework before you interview. If you feel excited after reading a company’s culture page, it’s a good sign that it could be a great place for you to work.

Keep in mind that both you and the company are interviewing each other to see if there is a mutual fit. How the interview process works, the interviewers’ attitudes, and the kinds of questions they ask (or don’t ask) will tell you a lot about how they work and what they value. Asking questions will help you understand if it’s a place you want to work at:

Tell me about a time someone on your team was promoted (what do they value?)
Tell me about a time someone on your team was let go (what’s unacceptable?)
What was something questionable you’ve been asked to do recently? (are they evil?)
What was something you did recently even though others disagreed with it? (do they trust their employees?)

These answers will help you evaluate their claims about the company’s culture.

Ugh

Interviews aren’t the most pleasant experience, but they can be prepared for. If you’re still struggling, ping me on Twitter and I’ll try my best to help.

Interviews generally suck and there’s no reason to feel bad about not being good at it. Learning to separate your value as engineer/self-worth from your interviewing skills will greatly help with your mental health. Please take the time for self-care!

Good luck!

Migrating from Medium to Gatsby

Sun, 17 Mar 2019 03:45:03 GMT

I recently moved my blog from Medium to a self-managed blog built with Gatsby in the open, then deployed on Netlify. After a few weeks of fiddling around, I feel like I’ve landed on something I’m mostly happy with.

Despite my many new & old frustrations with Medium, I really enjoyed the writing experience. Whenever I’ve built my own blogs in the past, inevitably, I spent more time designing and building the damn thing instead of writing content. On Medium, I could just write.

In this post I’ll describe how I did the transition, and what tools I found along the way that have made the experience of managing my own blog with Gatsby a somewhat painless one. Let’s get started!

Exporting your content off of Medium

The first step is to download all your information from Medium. It’ll be sent to you as .zip file containing all your data, including published & draft posts you’ve written. Once you’ve uncompressed your files, you’ll see a bunch of folders:

Medium posts are exported as html files

Medium posts are exported as html files in the posts folder, so we’ll want something to convert them to markdown. Alternatively, you could use something like gatsby-source-medium or gatsby-source-rss to add this data to Gatsby’s GraphQL endpoint. I preferred having actual files in my repo so I could make edits as necessary.

After some googling, I found medium-2-md by Gautam Dhameja which seemed promising. You point this script at a local folder containing your Medium posts, and it generates a folder full of markdown files together with basic frontmatter. Having frontmatter included is useful, because it allows us to add interesting metadata to our posts that we can then use when building our blog in Gatsby. Frontmatter looks like this (everything between the ---):

---
title: "My blog post"
description: >-
  This is a description of my awesome blog post
date: "2019-03-17T00:52:08.562Z"
categories:
  - stuff n things
keywords:
  - my blog post
this:
  - is an array
  - of strings
arbitraryData: is fine to add
---

My content that isn't frontmatter

To begin, run the following script, pointing it to the folder which houses your Medium html posts:

npx medium-2-md convertLocal path/to/medium-export/posts -f

If you want to convert your drafts as well, add the -d flag to the command. When the script completes, it’ll place a folder within posts called md_<series of numbers>, which contains all your published posts in markdown format.

Converted posts in markdown format

Getting started with Gatsby

Now that we have our posts, we can get our blog going! I started by throwing something together in Sketch, as I found it helpful for me to think about different ideas I wanted to try in the design of my blog. Here’s what I originally came up with (quite different from what I actually built!):

My original design for my blog

Setting up

Next, let’s get our repo created using the gatsby-starter-blog starter. There are lots of different starters when you’re creating something with Gatsby, but I found this one good enough to be a base. Follow the instructions in the gatsby-starter-blog repo after you’ve also installed gatsby-cli. If you did it right, you should have a new folder with the following (or similar) structure:

What your folder structure should look like

At this point, I moved my markdown posts into the content/blog folder, and had to do a bunch of cleanup to prettify the markdown. One thing that made the conversion process difficult was that in my Medium posts, I added code snippets by embedding GitHub gists. This meant that the code snippets in my posts didn’t get converted, so I had to do some manual work here with copypasta.

How does Gatsby even?

Once you’ve cleaned up your posts, you should have a bare bones, basic blog built with Gatsby. I’m not going to comprehensively cover what Gatsby does or how it works in the post, but the docs and tutorial are excellent ways to get started. What you should know about Gatsby is that it’s really a static progressive web app (PWA) generator. It’s like Jekyll and create-react-app combined. In their own words:

Gatsby.js is a static PWA (Progressive Web App) generator. You get code and data splitting out-of-the-box. Gatsby loads only the critical HTML, CSS, data, and JavaScript so your site loads as fast as possible. Once loaded, Gatsby prefetches resources for other pages so clicking around the site feels incredibly fast.

Which parts of my Gatsby app are static? It wasn’t initially obvious to me. It eventually dawned on me that Gatsby tries to do as many things at build time in order to generate static assets. For example, if you can have Gatsby query your data at build time (such as from your filesystem, an external API, a database, etc), then static files can be generated from that data. The resulting artifact is then completely static.

During run time, your Gatsby app can respond immediately with static assets while hydrating itself with additional data / interactivity as needed after initial render. It’s not just a static site generator! It also uses GraphQL in a fairly novel way as a layer for your React client to work with. For example, the markdown blog posts you’ve added, the metadata for your site, the image assets and more are all exposed to your React client via GraphQL.

The cool thing about Gatsby’s architecture, is that in addition to the runtime ecosystem for application concerns via React components, it also opens up the possibility for reusable plugins that work on your build itself. For example, if you wanted to create an RSS feed for your blog, you could quickly download a plugin (gatsby-plugin-feed) that can do that for you at build time. That’s amazing!

Automate all the things

Throughout the process of creating my blog, I found the following tools that made my life easier.

Deploying your blog with Netlify

Getting your blog deployed with Netlify is a breeze. Once you’ve created a new site in Netlify, you can quickly turn on automatic deployments as well as deploy previews. Deploy previews are built for every PR, and lets you quickly take a look at your changes before merging into master. You’ll also want to use Netlify’s DNS if you can, because that will allow them to provision a wildcard SSL certificate for you, meaning both your “naked” (meaning https://no.lol) domain and “www” (https://www.no.lol) domain will both have SSL.

Add the lighthousebot for continuous performance testing

After some headscratching, I finally figured out how to get the lighthousebot to automatically run in CI for every pull request. If you’re not familiar with Lighthouse, it’s a developer tool released by the Chrome team that helps you audit your site for performance, accessibility, progressive web apps, and more. You can run a lighthouse audit in your Chrome DevTools without installing anything:

Run a lighthouse audit on your site in the Chrome DevTools

To get started with lighthousebot, follow the instructions in the lighthousebot repo. You’ll need to:

Add @lighthousebot as a collaborator to your repo
Request a lighthousebot API key
Add the API key as an environment variable to TravisCI
Then run it against your Netlify deploy preview so you can look at score changes before merging your PR

lighthousebot will leave a comment in your PR

Because you need to wait for the Netlify deploy preview to finish before you can run lighthousebot, you’ll need a little npm package called wait-for-netlify-preview by Alexander Lichter to let TravisCI wait before running the lighthouse audit. To get this to work, install wait-for-netlify-preview as a dev dependency, add an access token with the repo permission, and add that as a environment variable in TravisCI: GITHUB_API_TOKEN = <your access token>

If you did it right, you should have two environment variables set in TravisCI:

What your TravisCI environment variables should look like

Here’s what I added to my TravisCI config and package.json:

.travis.yml

jobs:
  include:
    - stage: Test
      install: yarn install --frozen-lockfile
      script: yarn test
    - stage: Lighthouse
      if: type = pull_request
      install: yarn install --frozen-lockfile
      script: yarn run lh --perf 90 --pwa 90 --a11y 90 --bp 90 --seo 90 "$(wait-for-netlify-preview)"

package.json

{
  "scripts": {
    "lh": "lighthousebot"
  }
}

Now, when you open a PR, you’ll see the following stages in TravisCI:

Your TravisCI stages should look like this

This is a pretty nice setup! Gatsby gives you incredible performance out of the box, so this addition to your CI process ensures that the code you add won’t slow your site down too much ;)

Bring on the bots

Some other bots I also found useful:

delete-merged-branch: automatically deletes merged branches
renovate: keeps your dependencies up to date, similar to greenkeeper. I like that you can specify a schedule so the PRs don’t get too noisy
bors: if you have multiple people contributing to your blog, bors is incredibly helpful! I use this in a bunch of my open source libraries. It helps you prevent “semantic conflicts” as you merge multiple PRs. It’s also pretty cool being able to merge PRs simply by leaving a comment (“bors r+“)

If you have any questions or want more details, tweet at me. I hope you found this post useful, happy blogging!

#1 Should I Become a Tech Lead?

Sat, 09 Mar 2019 19:21:07 GMT

I recently tweeted that I was starting an experiment. 26 people applied to try this out! Over the next couple of weeks, I’ll be speaking to as many of them as I can in one-on-one (1:1) meetings over Google Hangouts. With their permission, I hope to be able to share some of the advice I’ve given them with you.

Trying a little experiment: starting next Sat (03/09), I'll be doing one-on-one meetings with people from under-represented minorities who are interested in: career/manager/tech advice, feedback on conference proposals, and more!

💁🏻‍♀️ Go here to apply: https://t.co/O2ve1Lp0pl
— lauren (@poteto) March 2, 2019

Here is today’s topic — growing as an engineer in the context of becoming a tech lead. The person I spoke to has been doing frontend development for most of their career, but was wondering if they needed to become fullstack in order to do a good job as a lead.

When we spoke, they told me that they didn’t feel like they were ready because they didn’t feel good enough yet on a technical level. That reminded me of myself when I first took on the role of a tech lead a few years ago. At the time, I didn’t understand what being a tech lead really meant.

What does a tech lead do anyway?

I used to think that the tech lead has to be the best programmer on the team. I was worried at the time because I felt like I had so much more to learn. If you stop and think about it from your manager’s perspective though, moving your best programmer away from contributing code to helping out with managing the team isn’t always a good decision. You’re taking away some of the work this person is really good at, and you’re moving them into a role where they need to do more of what they might not be great at — managing people.

The tech lead is an interesting role. You’re a hybrid engineer and leader who has to manage a small team, without much authority. The best tech leads are typically the engineers who’ve made a big impact in the way the team ships product. That could be engineering wise, for example in the form of tooling they’ve created to make other engineers on the team more productive. More commonly, it’s because this engineer has strong organizational and leadership skills that makes everyone else on the team more effective. Have you heard of the “10x engineer”? That’s what the best tech leads are, and not because they are 10x better.

A 10x engineer isn't someone who is 10x better than those around them, but someone who makes those around them 10x better.

Becoming a 10x Developer: 10 Ways to be a Better Teammatehttps://t.co/4Kx0yNJ4ji pic.twitter.com/H90xkUuNWD
— Kate Heddleston (@heddle317) March 12, 2018

The Voight Kampff Test for Engineering Managers

I attended the Calibrate conference last year, and I had the privilege of seeing Nick Caldwell speak about “Igniting the fire”. One of his slides spoke about the “Voight Kampff test” for engineering managers. The Voight Kampff test is a reference from Blade Runner, and it’s essentially a polygraph-like machine used by the LAPD’s Blade Runners to assist in the testing of an individual to see whether they are a replicant (robot) or not.

https://speakerdeck.com/calibrate/ignite-the-fire-management-that-sparks-new-leaders?slide=5

by Nick Caldwell

I ran through these questions with them in our 1:1 and I found their answers to be somewhere in the middle. They acknowledged that they think architecture is important, but so are the people on the team. They didn’t want to spend time on recruiting/hiring though, which sounds to me like this person wouldn’t want to be an engineering manager at this point. Without knowing too much more about what they valued and how they worked, I suggested that moving into a tech lead role could be something worth trying out. Knowing what it is about their job that brought joy to them was key though, so I advised them to wait and see. In the meantime, figure out what it is that brings them satisfaction at work.

At worst, they’d figure out in a couple of months/years that being a tech lead isn’t for them. There’s a risk they might do poorly in this new role, so leaning into this takes a lot of self-awareness. They could lose their job if they completely mess it up! At best, you might learn that you really enjoy making your team more effective/productive, and consider a future role in engineering management. Either way, unless you truly make a big mess, you’ll come out of it having learnt some valuable lessons.

There are only 2 types of decisions

There are really only 2 types of decisions you’ll face in your career: Type 1 and Type 2. Type 1 decisions are usually irreversible (or at least extremely difficult to reverse). Think quitting your job, or selling your company. Once you make a Type 1 decision, there’s often no going back.

Type 2 decisions are easy to reverse. For example, taking on work in a new programming language, agreeing to do a talk, or accepting a promotion. While you might still consider Type 2 decisions important to deliberate about, they can be reversed with enough time and effort. In this case, I advised them that moving to a tech lead role is probably a Type 2 decision.

If you’re considering taking on a new role as a tech lead or engineering manager, ask your manager what type of decision this is you’re making. If it’s Type 2, don’t agonize over the decision too much. Speak to as many people as you can and get their advice, but don’t lose too much sleep over it! If you have a strong support network at work, including your manager, it could be a potentially rewarding change.

Growing as an engineer

Becoming a tech lead can be rewarding if you know what the role involves, and you think you might enjoy being a “force multiplier”. If you’re interested in learning more about engineering management, I highly recommend “The Manager’s Path” by Camille Fournier. It goes into greater detail about the path to engineering management.

That said, engineering management isn’t the only career path for growth. Depending on where you work, your company may have a technical track that lets you go deeper into developing your technical skills. Keep in mind though, that even if you’re a principle architect, your work will shift more and more towards understanding people & people skills, and less about raw programming ability.

I’ll cover more on this topic in a later post.

Good luck!

Exploring the Strongly Typed Graph

Sun, 28 Oct 2018 01:53:04 GMT

The “Strongly Typed Graph” is something I’ve been thinking about lately. I believe it could significantly improve developer productivity in large, microservice heavy organizations.

To be clear, this is still an exploration. An early idea I wanted to throw out there. But before I dive into what it is and what it could solve, let me give you some context about our problem, and why I think this idea is compelling.

⚠️ Warning: It may not solve the exact problem that you have. Read more and decide for yourself, this is not a silver bullet or a “best practice”.

👩🏻‍💻 I assume some basic knowledge of gRPC/Thrift, GraphQL and TypeScript/Flow.

Move fast and learn things

I currently work in a large, microservice heavy organization. Microservices have worked well for us given our loosely coupled org structure. We optimize for rapid learning and innovation in our respective business sub-domains. The larger domain being entertainment, for content creation at scale. Think creating thousands of high quality shows (movies and TV series) a year, across domains such as financing, production, business/legal obligations, casting/staffing of productions, and more.

"Organizations which design systems … are constrained to produce designs which are copies of the communication structures of these organizations."— M. Conway

We moved fast, building a core set of applications in a few years. But, these applications were silos, and disconnected from each other. We would update something in one, and wonder why it wasn’t updated in the other.

This was the price of moving fast and breaking things. It was impossible at the time to understand what the larger domain was. In hindsight, these connections are obvious. But in the beginning, it was like foraging for a random selection of mushrooms in a forest. Only to later discover that they all share deep, interconnected roots.

Everything is a graph

Creating content is a creative process, and made possible by the collaboration of different business units. Creating a new show is like creating a startup. You worry about where the money is going to come from. Who’s the CEO and COO? Is the business model sound? How will we hire people to do the work?

In entertainment, it’s the same questions. How we will finance the show? Who will be the showrunner (for TV), or director (for movies)? Is the script any good? How will we cast actors and actresses, and hire the best grips, editors, camera operators, and more?

In moving fast, we were also able to learn fast. We learned that these sub-domains made up a larger graph. And that we needed to connect them together to truly push the business forward.

Example graph from neo4j movie dataset

Move fast and grow the network

We needed to ensure our data was consistent across domains, but allow teams to independently evolve their sub-domains. The challenge–the tension between correctness and productivity that is difficult to balance, especially in large organizations.

We want teams to be able to accelerate their rate of innovation, but in a way that makes the collective network stronger.

End-to-end type coverage

The idea of end-to-end type coverage is simple and compelling. It is the combination of strongly typed technologies such as gRPC/Thrift, GraphQL, and TypeScript/Flow across the stack, from backend to frontend. If you’re interested in learning more about type systems, check out my talk at React Rally 2018.

Type systems are not new inventions. You may have used a strongly typed language like Java, C#, Go, Rust, and more. The static type systems you’re familiar with give you compile time guarantees. They guarantee that the code you have written is type safe. They don’t guarantee that the services you depend on are type safe.

In other words, they can’t provide any runtime type guarantees (not the same as runtime type checking). You may trust that some JSON has foo, bar, and baz defined, but an external service could return otherwise. A TypeScript library (io-ts by the amazing gcanti) does exist for a runtime type system, interestingly enough.

io-ts aside, having end-to-end type coverage won’t provide any runtime type guarantees. Services can and will fail in ways you don’t expect. An end-to-end type system is not meant to give you type safety at runtime boundaries, but it enhances type safety for dependencies at compile time.

Picture this. You’re at your editor, coding up a storm for a new client-side UI. A VS Code extension allows you to hook up to any GraphQL endpoint, and immediately receive type information. Because it’s subscribed to the endpoint, it can also alert you when fields you’re using break (their type changes, or they’re removed/deprecated). In real time.

Highly Aligned, Loosely Coupled

The “Strongly Typed Graph” builds upon end-to-end type coverage and connects diverse domains into a single graph. It gives teams near real-time visibility of how changes in the larger graph affect your entire organization. As a reminder, this architecture is still only an exploration!

Architecture for the Strongly Typed Graph

What’s exciting about this are just some of the possibilities at various levels in the organization:

autocompletion in your editor/IDE while building client UIs. See new fields “come online” as other teams evolve the graph, right in your editor
understanding how long using a field in the graph will impact your page load time
pull request feedback when a change in your schema is going to break clients of that data
email/slack notifications when field(s) you rely on become deprecated or changed in a breaking fashion (type change or removal)
transform/map low level IDLs to product facing GraphQL schemas
visibility into how the larger graph evolves over time
(not in the diagram) orchestrate distributed writes across multiple systems

There are a few major pieces to this proposed architecture. The two I want to highlight are the schema registry, and the domain graph itself.

Schema registry

The schema registry stores and handles the analysis of GraphQL SDLs (Schema Definition Language). Microservices push their schema changes to the registry before deployment. The registry tracks how schemas change over time and alerts users of specific fields whenever there are deprecations or removals. These alerts can surface through various hooks, for example in GitHub/Bitbucket pull requests, emails, Slack notifications, and more.

If you rely on a field from the domain graph, you should receive an alert if it’s deprecated or removed. You should also receive an alert when you make a change that will break clients.

Domain graph

The domain graph retrieves GraphQL SDLs from the schema registry, and stitches them together. Incoming requests include client metadata, so we can track field usage on a per client basis. Reads/writes should passthrough to the respective microservice. Being a single access point, this service must be highly available.

How does this work in practice?

The goal is to improve correctness and productivity across a large organization. Tooling still needs to be built, but some of these things (such as schema management) are already being worked on by Apollo. For example, Apollo Engine is a SaaS that they’re building that gives insights into performance, schema validation and so forth.

I haven’t seen this topic discussed heavily yet, so it’s still pretty early in the adoption curve. This is a video that discusses the idea of an end-to-end type system. It’s one of the only resources on this topic I’ve found so far.

If you are building something similar, I would love to hear more about your experience.

Thanks for reading!

Commit to Commit

Wed, 28 Feb 2018 18:01:00 GMT

Commitment can be terrifying. Broken promises are the surest way down the waterslide of low morale.

When someone comes to you with a problem, don’t react immediately. Commit to commit, then follow up quickly. Give a specific date when you’ll get back to them with a commitment. “Thanks for the context about the bug, I’ll get back to you tomorrow morning with a decision on how we’ll move forward”.

Keep the window short. Hearing “I’ll get back to you” without the follow up will quickly lose the trust your customers have in your team.

This doesn’t only apply when speaking with customers. Whenever you need time to understand and think about a decision–commit to commit–be it your manager, your peers, or your parents.

Move forward without hesitation

Commitment is important, because it creates clarity around direction and priorities for your team. Your team can be better aligned around common objectives, and it develops an ability to learn from mistakes.

When you commit to commit, your team has a chance to understand what your customer is saying, why they’re feeling that way, and where they’re coming from. You get the chance to come back with a solid answer that the whole team has bought into.

In my next post, I plan to write about what I’ve learned Patrick Lencioni’s book, “The Five Dysfunctions of a Team”. I’ll also share how my team applies it.

Thanks for reading! 😊

An Engineer’s Guide to Communication

Mon, 26 Feb 2018 07:06:39 GMT

It’s far too easy to be misunderstood. Trying to get your idea or point across to someone can often feel frustrating and difficult.

You’re not wrong for feeling like you, or they, just don’t get it. It’s tempting to believe that maybe you were never meant to be a good communicator, let alone a public speaker, or an engineering lead. Worse, you may think poorly of someone because they can’t seem to understand what you’re trying to say.

Communication is inherently lossy. What you don’t say is as important as what you do say. How you say it can matter more than what you actually say. It’s even lossier in writing. Communication will likely never be lossless, until we can communicate telepathically, I suppose.

That doesn’t mean you shouldn’t try–I’ve been awkward and shy my whole life, and being a good communicator takes extra effort on my part. But it’s important that I try, even if it’ll never be perfect. Things don’t get better without effort.

“Computers are easy; people are hard”

As an industry, we solve problems with technology. That’s what we were hired to do. The mistake is that we tend to also see communication and people issues as problems we can solve with technology. I’ve been personally guilty of this on more than one occasion.

Why should we learn how to communicate better? It’s because more often than not, software problems tend to be people problems.

My favorite talk from last year, by Bridget Kromhout

It’s easy to believe that, if only we used containers, microservices, serverless, or nocode–that just by using this new technology, we will solve all our problems. Take microservices, for example.

Netflix is famous for supposedly “writing the book” on microservices. You might be forgiven to think that Netflix is successful because we have a microservice architecture. And that if you use it too, you could be as successful.

No. There are no silver bullets. There may never be one in our industry. If you’re not at Netflix’s size, microservices won’t help you, they will in fact slow you down with added complexity. Microservices are not a technical solution. They’re an organizational optimization. They are a way to allow teams to operate at scale, only if they are communicating effectively first.

Listen first, understand second, speak last

To communicate effectively, I practice a simple rule. When I speak with others, I seek to listen first, understand second, and speak last.

When I listen first, I give others a chance to be heard. Everyone wants to be heard.

When I ask questions, I understand what they mean, where they’re coming from, and why they have the opinions that they have.

I speak last, because I get the benefit of hearing everyone’s opinion before I volunteer my own.

When you go to your next team meeting, give it a try. Don’t say the first thing that comes to your mind. You’ll get your turn.

In Netflix’s high trust culture, if we need to make a decision, one of us acts as the informed captain. In a team built on trust, we don’t wait for consensus. We disagree, and we commit. When the captain of any particular decision is reasonably confident of the right bet for us to take, they decide and we take that bet. But to gain commitment, it’s important to listen and understand first.

Communicating non-violently

I have strong opinions about software. You may have them too. Some of us may even feel that not knowing about the link tag (and a laundry list of other things) makes you unworthy of our craft.

It’s fine to have strong opinions and judgments. If you want to communicate with someone though, if you want them to see what you see, you should seek to communicate non-violently. If “violent” means acting in ways that result in hurt or harm, than much of how we communicate could be called violent communication.

When we lead with our judgments–discriminating, speaking without listening, judging who belongs “in our craft” and who doesn’t–people close up to you. You’ll never be able to let them see what you see, or think what you think, if you don’t take the time to understand what they see or think first. Have a little empathy.

If you’re right, all the better, because they’re more likely to accept what you say. It’s a simple framework.

Observation — facts and data without judgement or evaluation
Feeling — state how you feel
Need — state your need underlying this feeling
Request — a specific action to address said need

The most important part to me is in taking a step back to understand why I feel or judge something a certain way. The leap from observation to judgement happens very quickly. We might observe that someone on your team submits code without writing any tests. That’s fine. The issue is in quickly adding your judgement that they have no respect for the team.

Both of you would agree that they don’t write tests in their pull requests. It’s an objective fact. But before you rush to pass judgment, you should give them a chance to explain.

You could say something like: “When you submit a pull request without tests, it makes me feel worried that we’re introducing regressions.” This gives the person space and opportunity to provide new information. They might say, “I’m sorry, I’m unfamiliar with the testing framework, there was no documentation and I was afraid of asking.” You wouldn’t have known that if you didn’t ask. Now, you’ve uncovered an important issue and can work to solve it together.

Communicating well will make you a better engineer, and a better person. It’s certainly not easy. But it’s important that you try, even if it’ll never be perfect. Things don’t get better without effort.

Thanks to Zach Wentz for reviewing and for sharing “non-violent communication” with me.

Skeleton Screen Loading in Ember.js

Wed, 11 Oct 2017 21:39:53 GMT

Skeleton screen loading (also known as placeholder loading) is a technique that enhances the perception of loading in your application. Typically, the loading state of an application is indicated by some kind of loading spinner or progress bar. Unfortunately, this can sometimes backfire and cause the app to feel slower than it actually is.

The idea behind skeleton screens is instead to “show content as soon as possible”, by using a “skeleton” or placeholder representation of the actual UI in its place while content is being loaded. From what I’ve seen in the wild, this is typically a wireframe version of the UI with subtle animations, but there are no hard and fast rules.

Don’t make people wait for content to load before seeing the screen they’re expecting. Show the screen immediately, and use placeholder text, graphics, or animations to identify where content isn’t available yet. Replace these placeholder elements as the content loads. — Apple iOS Human Interface Guidelines

I won’t delve into too much detail on the concept. In this post, I’d like to demonstrate how you can achieve skeleton screen loading in your Ember.js application.

Don’t fetch your data in the route

You’ve probably been told that you should always fetch data in the route, typically in the model hook:

import Ember from 'ember';

const { Route } = Ember;

export default Route.extend({
  model({ fullName }) {
    return this.store.queryRecord('user', { fullName });
  }
});

The nice thing about this approach, is that an unresolved promise returned in this hook will trigger the route’s loading substate. This is usually where you would place your loading spinner component, for example. This is fine when you’re working with a non-query-param-enabled route, but if you do have to support query params or refresh the model based on some user input, you might notice annoying UX (ember-twiddle example) as a result of this behavior.

Whenever your user tries to change a query param linked value that refreshes the model, the model hook re-fires. If you’re trying to search for something, for example, this causes an unacceptable amount of jank.

We can do better.

Move data loading out of your route

What we really want to avoid is the entire application transitioning to a loading substate whenever some data is loading. This is regardless of whether you use query params. In Ember’s loading substate, your app is no longer responsive. We should avoid that.

However, moving this out from the route raises important questions. Without the built-in logic for the loading substate, what can we do to avoid rebuilding it?

ember-concurrency saves the day

Instead of loading data in the route, you can do so in a controller or a component. I personally prefer using non-presentational components to load data — I call them “loader” components, sometimes also known as container components.

import Ember from 'ember';
import { task, timeout } from 'ember-concurrency';

const { Component, get, set } = Ember;

export default Component.extend({
  tagName: '',
  init() {
    this._super(...arguments);
    this.data = [];
  },

  didReceiveAttrs() {
    let query = get(this, 'query');
    get(this, 'fetchData').perform(query);
  },

  fetchData: task(function*(query) {
    yield timeout(1000);
    let users = yield get(this, 'store').queryRecord('user', query);
    return set(this, 'data', users);
  }).restartable()
});

This approach also works with a controller, but you won’t have any lifecycle hooks to work with. Instead you’ll have an action call the ember-concurrency task that fetches data in response to some user input.

In its simplest form, a loader component is a tag-less component that performs an ember-concurrency task whenever some property being passed to it is changed. For example, this could be a query params hash, or other kind of user input. Then, all this loader component does is yield out specific properties:

{{yield (hash
    isRunning=fetchData.isRunning
    data=data)
}}

With ember-concurrency, we don’t have to rebuild the wheel to recreate the loading substate within our component. We can instead leverage its “derived state” and change our UI accordingly. Here’s a simple example of how to use this loader component:

{{#my-loader query=query as |loader|}}
  {{#if loader.isRunning}}
    <p>Loading...</p>
  {{else}}
    {{#each loader.data as |user|}}
      {{user.fullName}}
    {{/each}}
  {{/if}}
{{/my-loader}}

With this change, we now have granular control over how our loading substate is rendered in our application. Most importantly, you’ll note that loading data this way will no longer block interactivity in your UI. Now, adding skeleton screens in its place is easy, thanks to the ember-content-placeholders addon by Michał.

Because the addon relies on ember-cli-sass, I wasn’t able to include it in my ember-twiddle demo. I added a simple placeholder instead which provides a similar effect.

via Gfycat

Screencast taken with a terrible internet connection from an Airbnb in Berlin

Data loading with query params

If you do use query params, you can still adopt the same approach. Offir and I wrote an addon that improves upon the experience in working with query params.

Instead of defining query params in both your route and controller, with this addon you can define them in one place as a query param map.

This map is the source of truth for your query params, and will generate a mixin that you can then add into your controller. The mixin adds very helpful properties and methods that makes working with query params a breeze! Once you’ve added ember-parachute to your app, you can move your query param configuration away from your route and into the controller.

import Ember from 'ember';
import QueryParams from 'ember-parachute';

export const AppQueryParams = new QueryParams({
  query: {
    as: 'q',
    defaultValue: 'puppy',
    refresh: true
  }
});
const { Controller, computed: { or } } = Ember;

export default Controller.extend(AppQueryParams.Mixin, {
  queryParamsChanged: or('queryParamsState.{query}.changed')
});

Because your route no longer fetches data, you can fetch data in your controller or component with an ember-concurrency task. This task is performed in response to user input, either via a component’s lifecycle hook, or by an explicit action call. Use the task’s derived state to determine the loading substate instead.

What should I use the route for?

In my applications, we still use the route for specific behavior, such as enforcing valid route (not query) params. I currently work on a calendar application, so visiting /2017/15 is obviously not valid. We handle that validation logic in the route and redirect to a valid date instead.

Obviously, this approach isn’t aligned with what is recommended in the guides. Unfortunately, at this moment in time, there is no real answer into developing a solid skeleton screen experience with the status quo. This approach with ember-concurrency and moving data loading out of the route has worked well for us in the meantime, and I’m curious to hear what your thoughts and experiences are.

Thanks for reading!

I Am Still Learning

Tue, 30 May 2017 14:01:45 GMT

I’m afraid

I was afraid when I started college in Australia, 4,000 miles away from home. I spent 3 years in vocational design school, and the thought of going back into academia was daunting. My grades were always terrible. Compared to my peers, I didn’t think I was smart enough.

I was afraid when we started a startup. I didn’t know if I was making the right decision starting a business right out of college. Because neither of us could code, we spent our savings hiring a developer. They didn’t come through. Neither did our savings.

I was afraid when I started my first job after my startup failed. The only programming I had ever done was over-engineered Excel spreadsheets and some HTML and CSS. Going into my first job, I barely knew enough JavaScript to start work as a front-end developer.

I was afraid when I first started blogging about Ember. It was my first time learning how to use a framework (in any language). Who would bother reading?

I was afraid when Leah and Tom reached out to me to speak at EmberConf. I barely had any experience, and had never been to a conference, let alone speak at one.

I was afraid to choose React. It was a new job, and I really didn’t want to destroy their business if I messed up. Up till then, all I had done was Ember.

I was afraid when I started a new job in Boston. Here I was, moving my life again, this time 10,000 miles away. I had to start my adult life over once more.

I was afraid going into my interview with Netflix. I don’t have a CS background. I can’t balance a binary tree to save my life. I was going to fail this interview spectacularly.

I was afraid when I was asked to take on the engineering manager role in my team. I’ve never been great with people and I love programming too much.

I’m afraid about writing this. As a woman in tech, I have a higher bar to climb to prove my worth. I already have something to prove, I don’t need one more.

And I’m going to keep being afraid. Trying something that seems out of reach is always frightening.

I’m still learning

I studied the hardest I ever did in college, graduating in the dean’s list.

Starting a business is hard. We went through the startup roller-coaster with some of the best people we were fortunate enough to meet. We failed, but I learned enough programming to land a job.

My first mentor was Chris. He taught me a ton. I can still vividly remember working with him through a thorny problem with JavaScript Promises. The way I approach programming these days still has some of his influence.

Homely.com.au still uses some of my initial legwork to get them going with React.

My blog is the best thing I have ever done for my career. In 2015, I spoke at EmberConf. As well as 2016. And 2017. DockYard remains one of the best places I’ve worked at.

I got the job at Netflix. It’s awesome, and I’m always hiring. I won’t ask you CS trivia questions.

I’m now the engineering manager for the Talent Innovation Engineering team at Netflix. I hired and lead an 11 strong team to reinvent the way Netflix discovers and manages talent in the entertainment industry.

I’m no longer afraid about having to “prove my worth”. I’ve proven it many times over. I’ll never stop learning, and I want to help others do the same.

Learning from fear

I’ve come to learn that fear is something to be yearned for. If you’re not afraid, you’re too comfortable. Your best work happens when you’re in that sweet spot of being just uncomfortable enough.

Surround yourself with stunning people. That’s the only way you’ll learn anything.

We don’t learn alone.

Public speaking was my greatest fear. It might be yours too. Now, my greatest fear is that I will grow too comfortable.

Whatever it is you’re afraid of doing next, know that you’re not alone. To be afraid is to be human. When you’re afraid, it’s a great signal that you’re on to a learning opportunity.

Learn to welcome fear. Learn from fear. No one learns and develops skills in a bubble.

Now repeat after me:

“I am still learning”

Thanks to Sam French Stewart and Michael Soutar for reviewing.

Note: Ancora imparo, or “I am still learning”, is the motto of my alma mater.

Rise From the Ashes — Incremental APIs With Phoenix

Fri, 12 Aug 2016 17:26:46 GMT

Much has been said about the Elixir language and the Phoenix framework —Phoenix’s performance without compromise makes it a compelling choice in a world where problems are increasingly concurrent and real-time.

Despite Phoenix’s attractiveness, chances are you have business requirements that disallow you from dropping work on existing APIs that still need to be supported. And so you might consider Phoenix no longer viable, and dismiss it to your ever-growing list of shiny toys to check out — someday.

What if we could incrementally replace our legacy API with Phoenix, one endpoint at a time? We could make a compelling argument by showcasing performance and maintainability gains, without committing to a rewrite.

In science fiction (and perhaps someday reality), transforming an uninhabitable planet into an inhabitable one is known as “terraforming”, or literally “Earth-shaping”. It’s an apt metaphor for a little plug I co-authored with Dan McClain. It’s available on GitHub.

Using Terraform, you can create a Phoenix app that handles one or more endpoints, and forward un-handled requests to your legacy API. If some network latency is not a significant issue, you might find this plug useful.

Discovery

The basic idea is this — if a route is defined on our Phoenix app, we’ll handle the request. If it’s not, we forward the request on, and send its response back to the user.

In your Phoenix app, every incoming connection goes through a pipeline that you can readily examine at lib/my_app/endpoint.ex. You can see how a connection flows through the different plugs specified in this file. The connection is then piped into the router:

web/router.ex

# Add Terraform to your router
defmodule MyApp.Router do
  use Terraform, terraformer: MyApp.Terraformers.LegacyApi

  # ...
end

Terraforming the legacy API

By adding the Terraform plug to your router, it will then re-route those missing route connections to a plug that you define. And because this plug uses Plug.Router, you have an elegant DSL in which you can handle them:

terraformers/foo.ex

# Write a Terraformer to forward requests
defmodule MyApp.Terraformers.Foo do
  use Plug.Router

  plug :match
  plug :dispatch

  get "/v1/hello-world", do: send_resp(conn, 200, "Hello world")
  get _, do: send_resp(conn, 200, "Handle all GETs")

  options _, do: send_resp(conn, 200, "Handle all OPTIONs")
  delete  _, do: send_resp(conn, 200, "Handle all DELETEs")
  patch   _, do: send_resp(conn, 200, "Handle all PATCHs")
  post    _, do: send_resp(conn, 200, "Handle all POSTs")
  put     _, do: send_resp(conn, 200, "Handle all PUTs")

  match "/weird/api", via: :eat, do: send_resp(conn, 200, "eat it")
end

Basic example aside, we’d probably want to do an actual request on your API, and you can do so by writing a client for it. There are many ways to do it, and I’ve had success in doing so with HTTPoison and its Base module. For example:

terraformers/legacy_api.ex

# Use a client for your legacy API
defmodule MyApp.Terraformers.LegacyApi do
  alias MyApp.Clients.LegacyApi
  use Plug.Router

  plug :match
  plug :dispatch

  get _ do
    %{method: "GET", request_path: request_path, params: params, req_headers: req_headers} = conn
    res = LegacyApi.get!(request_path, req_headers, [params: Map.to_list(params)])
    send_response({:ok, conn, res})
  end

  def send_response({:ok, conn, %{headers: headers, status_code: status_code, body: body}}) do
    conn = %{conn | resp_headers: headers}
    send_resp(conn, status_code, body)
  end
end

And here is what a client might look like:

# Example taken from https://github.com/edgurgel/httpoison
# GitHub client example written with HTTPoison
defmodule GitHub do
  use HTTPoison.Base

  @expected_fields ~w(
    login id avatar_url gravatar_id url html_url followers_url
    following_url gists_url starred_url subscriptions_url
    organizations_url repos_url events_url received_events_url type
    site_admin name company blog location email hireable bio
    public_repos public_gists followers following created_at updated_at
  )

  def process_url(url) do
    "https://api.github.com" <> url
  end

  def process_response_body(body) do
    body
    |> Poison.decode!
    |> Map.take(@expected_fields)
    |> Enum.map(fn({k, v}) -> {String.to_atom(k), v} end)
  end
end

This forwards all un-handled GETs to our legacy API via our client, and sends the response back with the right headers as well. Since this is just a plug, you have access to the connection, so you can easily handle things like sessions and auth as well.

What about performance?

I ran some unscientific benchmarks on my 2014 13” MBP, and the results between the route backed by a Phoenix controller and our Terraform handler were insignificant.

# Route handled by Terraform
$ siege -c 255 -r 40 -b http://localhost:4000/v1/hello-world

Transactions:             10200 hits
Availability:             100.00 %
Elapsed time:             13.59 secs
Data transferred:         0.11 MB
Response time:            0.32 secs
Transaction rate:         750.55 trans/sec
Throughput:               0.01 MB/sec
Concurrency:              241.40
Successful transactions:  10200
Failed transactions:      0
Longest transaction:      0.79
Shortest transaction:     0.03

# Route handled by FooController
$ siege -c 255 -r 40 -b http://localhost:4000/v1/foo

Transactions:             10137 hits
Availability:             99.38 %
Elapsed time:             16.85 secs
Data transferred:         0.03 MB
Response time:            0.39 secs
Transaction rate:         601.60 trans/sec
Throughput:               0.00 MB/sec
Concurrency:              235.74
Successful transactions:  10137
Failed transactions:      63
Longest transaction:      1.03
Shortest transaction:     0.04

This was done via Siege, with 255 concurrent connections doing 40 parallel requests each. That said, there will obviously be additional latency from having the Phoenix app send and return responses from your older API, so use your best judgement.

Give it a spin

Is Phoenix as productive, reliable, and fast as many claim? With Terraform, trying out Phoenix on your current API is almost risk-free. Handle a single, simple endpoint and compare it with the performance and developer experience of your current stack. You can also view a simple demo of Terraform in action here.

Thanks for reading, and see you at ElixirConf!

Component dependency injection in Ember.js

Tue, 28 Jun 2016 17:01:02 GMT

The Dependency Injection (DI) pattern is a subset of Inversion of Control, and is a useful technique for decoupling the creation of a dependency from the object itself. Don’t let the terminology scare you though! DI is really just giving an object its instance variables.

For example, below is a simple example of the Player class being implicitly coupled to the Bag class. The Player is responsible for creating the dependent objects:

export default class Player {
  constructor() {
    this.inventory = new Bag({ /* ... */ });
  }

  add(item) {
    return this.inventory.add(item);
  }
}

let bob = new Player();

Although the example is simple, it’s fairly easy to see that this implementation could be difficult to test in isolation, as you now need to know about the Bag class in the Player class’ test. DI can help us here:

export default class Player {
  constructor({ storageObject }) {
    this.inventory = storageObject;
  }

  add(item) {
    return this.inventory.add(item);
  }
}

let bob = new Player({ storageObject: new Bag({ /* ... */ }));

In the second example, we “inverted control” of the player’s inventory, and now we pass the storage object instance at runtime. This means that in our test, we can simply stub the inventory object out:

test('it adds an item', function(assert) {
  let dummyStorage = { /* ... */ };
  let dummy = new Player({ storageObject: dummyStorage });

  assert.ok(/* ... */);
});

The Player class no longer needs to know anything about the Bag, and also allows other kinds of storage object classes to be used. Great!

Component Dependency Injection

I recently realized that the DI pattern can also be used to great effect in Ember components. For example, let’s say you have a container or parent component that uses multiple child components:

templates/application.hbs

{{edit-location location=location}}

components/edit-location.hbs

{{google-map
    lat=location.lat
    lng=location.lng
    setLatLng=(action "setLatLng")
    setMarkerRadius=(action "setMarkerRadius")
}}
{{edit-location-form location=location}}
{{location-activity location=location}}

The parent component edit-location’s primary responsibility is to provide UI to edit a location. It could have actions defined on it, like so:

components/edit-location.js

export default Component.extend({
  actions: {
    setLatLng(latLng) {
      // logic
    },

    setMarkerRadius(radius) {
      // logic
    }
  }
});

The google-map component provides UI for the user to drop a marker on a map, and adjust the radius around the marker by using the radius control. Needless to say, that UI interaction is quite difficult to test, and is tested in the google-map component test itself. Because the edit-location component is tightly coupled to its child components, testing it is no easy task. We need to make sure all the child components are setup just right, which introduces a lot of boilerplate in our component integration test.

Not my concern

In this scenario, the edit-location component itself shouldn’t need to concern itself with how the latLng and radius arguments are passed into its actions. The drag and drop UI is a concern of the google-map component, and as such should be tested in its own component integration test.

Using DI, we can decouple the edit-location component from its child components, and clean up our tests. This technique is currently only possible with contextual components due to the use of the component and hash helpers, which were made available in Ember 2.3.0.

application.hbs

{{edit-location
    location=location
    ui=(hash
      location-map=(component "google-map")
      location-form=(component "edit-location-form")
      location-activity=(component "location-activity"))
}}

We’ve passed in a hash of the child components using the hash and component helpers. This effectively inverts control to the template that calls the edit-location form:

components/edit-location.hbs

{{ui.location-map
    lat=location.lat
    lng=location.lng
    setLatLng=(action "setLatLng")
    setMarkerRadius=(action "setMarkerRadius")
}}
{{ui.location-form location=location}}
{{ui.location-activity location=location}}

Install the test helper:

ember install ember-test-component

Now, in our tests, we’ll need to write a little test helper (or use the addon above) to create a dummy component we can use to no-op (do nothing). Credit goes to @runspired for nudging me in the right direction:

tests/helpers/dummy-component.js

import Ember from 'ember';

const {
  Component,
  assign,
  getOwner
} = Ember;

export function registerDummyComponent(context, name = 'dummy-component', opts = {}) {
  let owner = getOwner(context);
  let options = assign({ tagName: 'dummy' }, opts);
  let DummyComponent = Component.extend(options);

  unregisterDummyComponent(context);
  owner.register(`component:${name}`, DummyComponent);
}

export function unregisterDummyComponent(context, name = 'dummy-component') {
  let owner = getOwner(context);

  if (owner.resolveRegistration(`component:${name}`)) {
    owner.unregister(`component:${name}`);
  }
}

This test helper registers a fake component in the container, making it available for us to use in our component integration test:

tests/integration/edit-location-test.js

test('it ...', function(assert) {
  registerDummyComponent(this);
  this.set('location', {});
  this.render(hbs`
    {{edit-location
        location=location
        ui=(hash
          location-map=(component "dummy-component")
          location-form=(component "dummy-component")
          location-activity=(component "dummy-component"))
    }}
  `);

  assert.ok(/* ... */);
});

Now we can test the edit-location component itself without worrying about setting up child components. That said, DI still allows us to test those child components integrating with edit-location, in a more controlled environment:

tests/integration/edit-location-test.js

test('it updates location via the form', function(assert) {
  registerDummyComponent(this);
  this.set('location', {});
  this.render(hbs`
    {{edit-location
        location=location
        ui=(hash
          location-map=(component "dummy-component")
          location-form=(component "edit-location-form")
          location-activity=(component "dummy-component"))
    }}
  `);

  assert.ok(/* ... */);

I hope you find this useful! It’s not a silver bullet by any stretch, but DI can help you write better isolated components and simplify your tests.

Until next time! 👋

Bringing Ecto Changesets into Ember.js

Fri, 17 Jun 2016 23:47:26 GMT

The past month or so, I’ve been working on an Elixir and Phoenix API for a client. I am blown away by how nice it is working with Elixir and functional programming (FP) concepts. FP feels more intuitive and less prone to “shoot yourself in the foot” scenarios compared to OOP. In fact, I try to use functional approaches wherever possible in JavaScript as well.

That isn’t to say that one is better than the other, but in my experience less unexpected behavior occurs in FP. It turns out whole classes of bugs disappear when embracing immutability and pure functions.

Ecto Changesets to the Rescue

In Elixir, we use Ecto, a DSL for writing queries and interacting with databases. One of the core concepts in Ecto is the changeset — an atomic collection of changes. Changes are validated and checked against database constraints (such as uniqueness) before casting. This ensures that we catch invalid data in the app layer before insertion into the database. Ecto is often confused with Rails’ ActiveRecord, but it isn’t an ORM, and shouldn’t be used like one.

The idea for bringing changesets into Ember occurred to me while I was working on a new client app. An edit page featured 3 forms, all bound to the same model. Each hidden form had separate “toggle”, “save” and “reset” actions. Using ember-form-for and ember-cp-validations, this turned out to be harder than I thought. Editing one form would immediately update the model with 2-way bindings. This was a poor user experience, since you might edit more than 1 form at a time, but want to separate saves and resets.

Changesets in Ember

In my mind, I could see a solution using changesets. Each form would have a separate changeset, so changes (and validations) would be independent. It turns out that this approach works really well, and I’m happy to announce that you can install it today as an addon with:

ember install ember-changeset
ember install ember-changeset-validations

I wrote the addon with compatibility in mind, so it’s easy to wire up with your favorite validation library. The simplest way to incorporate validations is to use ember-changeset-validations, a companion addon. It has a simple mental model, and there are no observers or CPs involved — just pure, plain JavaScript functions.

Let’s take a look at how ember-changeset is implemented, and we’ll also demonstrate how they align with Ember’s Data Down Actions Up (DDAU) philosophy.

Virtual Properties with unknownProperty and setUnknownProperty

The core concept behind ember-changeset is the definition of unknownProperty and setUnknownProperty. These methods are invoked (if present) in Ember.get or Ember.set whenever an Ember Object does not define a property. Ruby developers would be familiar with this behavior via the method_missing method. A colleague I used to work with wrote an excellent blog post on this topic, please check it out if you’re interested in finding out more!

For example:

let Person = EmberObject.extend({
  firstName: null,
  lastName: null,

  unknownProperty(key) {
    console.log(`Could not get ${key}!`);
  },

  setUnknownProperty(key, value) {
    console.log(`Could not set `${key} with ${value}!`);
  }
});

When a Person is created, trying to get or set a property other than firstName and lastName will invoke the unknownProperty and setUnknownProperty methods respectively:

let jim = Person.create({ firstName: 'Jim', lastName: 'Bob' });
jim.get('firstName'); // "Jim"
jim.get('fullName'); // "Could not get fullName!"
jim.set('age', 25); // "Could not set age with 25!"

These two methods allow us to proxy our changeset to the actual model, meaning we can hold back changes but still forward gets to the model.

Storing Changes

Our changeset needs a reference to the underlying model, as well as an internal list of changes to be applied. We can set this up in the init method of our object, which is invoked whenever a new instance is created.

export function changeset(obj, validateFn/*, validationMap */) {
  return EmberObject.extend({
    init() {
      this._super(...arguments);
      this._content = obj;
      this._changes = {};
      this._errors = {};
      this._validator = validateFn;
    }
  });
}

export default class Changeset {
  constructor() {
    return changeset(...arguments).create();
  }
}

We want to be able to forward gets to _content, but hold back sets on _changes, and this is easy enough to set up via virtual properties:

{
  unknownProperty(key) {
    let content = get(this, '_content');
    return get(content, key);
  },

  setUnknownProperty(key, value) {
    return this._validateAndSet(key, value);
  },

  _validateAndSet(key, value) {
    // if valid, set it on `_changes`
    // otherwise set it on `_errors`
  }
}

Since a changeset should only allow valid changes to be set, we validate the change using the validateFn function that was passed in to the changeset factory. If a change is valid, we add it to the hash of changes in _changes, and if it’s invalid and returns an error message, we add it to the hash of _errors.

Of course, there are more implementation details than that, but the concept remains unchanged. After defining a simple public API for using changesets, there wasn’t too much more code to add! For example, this is how you would use a changeset:

let changeset = new Changeset(user, validatorFn);
user.get('firstName'); // "Michael"
user.get('lastName'); // "Bolton"

changeset.set('firstName', 'Jim');
changeset.set('lastName', 'B');
changeset.get('isInvalid'); // true
changeset.get('errors'); // [{ key: 'lastName', validation: 'too short', value: 'B' }]
changeset.set('lastName', 'Bob');
changeset.get('isValid'); // true

user.get('firstName'); // "Michael"
user.get('lastName'); // "Bolton"

changeset.save(); // sets and saves valid changes on the user
user.get('firstName'); // "Jim"
user.get('lastName'); // "Bob"

Rolling back changes, and even merging them, becomes trivial with a changeset:

changeset.set('firstName', 'Milton');
changeset.get('isDirty'); // true
changeset.rollback();
changeset.get('isDirty'); // false

let changesetA = new Changeset(user, validatorFn);
let changesetB = new Changeset(user, validatorFn);
changesetA.set('firstName', 'Jim');
changesetB.set('firstName', 'Jimmy');
changesetB.set('lastName', 'Fallon');
let changesetC = changesetA.merge(changesetB);
changesetC.execute();
user.get('firstName'); // "Jimmy"
user.get('lastName'); // "Fallon"

Data Down Actions Up, Not 2-Way Bindings

One of the reasons DDAU is so strongly emphasized in Ember 2.x is because it helps us avoid shooting ourselves in the foot with 2 way bindings (2WBs). 2WBs were the “killer feature” of many JavaScript frameworks when they first debuted. As client side applications matured and became more sophisticated, developers realized that 2WBs were more harmful than useful. 2WBs led to instability and difficult debugging in the form of cascading changes, and React was the first library to attempt to solve this problem.

React’s breakthrough was in the use of a virtual DOM, a representation of the actual DOM as a tree-like data structure. Diffing the changes between the virtual and real DOM paved the way for the complete removal of 2WBs — the application simply re-renders whenever there is a change in value.

This continues to be a simpler mental model, and just like Elixir (and other functional languages), eliminates a whole class of bugs. DDAU in Ember.js is built upon the same idea, that data should flow one way.

Using changesets in Ember takes the DDAU philosophy used in rendering into the realm of interacting with client side view models. Instead of 2WBs, changesets allow one way data flow to a model, ensuring that they are always valid, and eliminating a whole class of synchronization headaches.

Is This Real Life?

When I dropped in ember-changeset and ember-changeset-validations into my client app, it instantly clicked with the way I’ve been writing Ember, using DDAU. My complex forms now have independent validations and changes, and I no longer need to worry about saving an unintended change in one form when I submit another.

Because ember-changeset can be used directly in place of an ember-data model, using it with a form library like ember-form-for is trivial using the changeset helper:

{{dummy-form changeset=(changeset model (action "validate"))}}

{{#form-for changeset as |f|}}
  {{f.text-field "firstName"}}
  {{f.text-field "lastName"}}
  {{f.date-field "birthDate"}}

  {{f.submit "Save"}}
{{/form-for}}

Validating Changesets

Validation becomes even simpler with changesets. Throughout Ember’s history, we have largely relied on addons like ember-validations which make extensive use of observers. Newer libraries like ember-cp-validations use computed properties (CPs) instead, but that still relies on 2WBs.

Using ember-changeset and ember-changeset-validations you can take a functional approach with validations. A validator function is passed into the changeset, that is invoked whenever a property is set. This validator function then looks up the appropriate validator (say presence or format) on the validation map, and returns true or an error message.

import {
  validatePresence,
  validateLength,
  validateConfirmation,
  validateFormat
} from 'ember-changeset-validations/validators';
import validateCustom from '../validators/custom'; // local validator
import validatePasswordStrength from '../validators/password-strength'; // local validator

export default {
  firstName: [
    validatePresence(true),
    validateLength({ min: 4 })
  ],
  lastName: validatePresence(true),
  age: validateCustom({ foo: 'bar' }),
  email: validateFormat({ type: 'email' }),
  password: [
    validateLength({ min: 8 }),
    validatePasswordStrength({ minScore: 80 })
  ],
  passwordConfirmation: validateConfirmation({ on: 'password' })
};

A validator like validatePresence is simply a function that returns a function:

validators/custom.js

export default function validateCustom({ foo, bar } = {}) {
  return (key, newValue, oldValue, changes) => {
    // validation logic
    // return `true` if valid || error message string if invalid
  }
}

Which is simpler to reason about compared to an OOP implementation that relies on extending base classes and holding on to state. Because validation maps are simply POJOs, composing validators is intuitive:

validations/user.js

import {
  validatePresence,
  validateLength
} from 'ember-changeset-validations/validators';

export default {
  firstName: validatePresence(true),
  lastName: validatePresence(true)
};

You can easily import other validations and combine them using Ember.assign or Ember.merge.

validations/adult.js

import Ember from 'ember';
import UserValidations from './user';
import { validateNumber } from 'ember-changeset-validations/validators';

const { assign } = Ember;

export const AdultValidations = {
  age: validateNumber({ gt: 18 })
};

export default assign({}, UserValidations, AdultValidations);

This approach lets you build up validations independent of the model. Ember Data models aren’t 1 to 1 representations of server-side records, they’re View Models. This means we shouldn’t need to validate them the same way we would a server-side model. For example, you might have User models in your application, and some of these users might have different roles that require different validation. Best of all, we don’t need to use observers or CPs!

The Only Constant is Change

I hope you enjoyed reading about the concept and implementation of changesets in Ember. DDAU on your models will make your life simpler and your app easier to reason about! Work is still on-going on these addons, so please try them out and let me know if you have any issues or feedback.

As always, thanks for reading!

Declarative Templating in Ember with Composable Helpers

Thu, 21 Apr 2016 17:24:46 GMT

Previously, I mentioned that Ember’s new Helper implementation landed in 1.13. In my opinion, helpers are one of the most useful, yet least talked about features in Ember.

Idiomatic Ember — The Sweet Spot of Performance & Productivity

In my EmberConf 2016 talk on Idiomatic Ember, I spoke about helpers in detail, showing how they can be used to power up and essentially extend Handlebars with custom functionality. These helpers can then be used to allow declarative templating — a style of templating by composing actions, and giving templates more responsibility with regards to presentational logic.

Together with fellow DockYarder Marten Schilstra, we’ve created the ember-composable-helpers addon. It’s a package of declarative helpers that lend themselves naturally for composition, and using it can help remove boilerplate code in your app. You can install it today with:

ember install ember-composable-helpers

One of my favorite helpers in the addon is the pipe helper (and its closure action cousin, pipe-action). This lets you declaratively compose actions in your template, instead of creating many variants in your Component:

{{perform-calculation
    add=(action "add")
    subtract=(action "subtract")
    multiply=(action "multiply")
    square=(action "square")
}}

perform-calculation/template.hbs

<button {{action (pipe add square) 2 4}}>Should be 36</button>
<button {{action (pipe subtract square) 4 2}}>Should be 4</button>
<button {{action (pipe multiply square) 5 5}}>Should be 625</button>

This pipe helper was inspired by Elixir’s pipe operator, which lets you write the following:

A(B(C(D(E), "F"), "G"), "H")

As a series of data transforms:

E
|> D()
|> C("F")
|> B("G")
|> A("H")

Using the pipe operator, we can naturally express how E is passed to the D function, then the return value of that function is passed into C as its first argument, and so on. I think we can agree that the pipe version is a lot easier to read!

If only you knew the power of the Helper

You can think of a helper as a primitive Keyword construct used by Ember and HTMLBars to extend the ordinary expressions provided by Handlebars. At its most basic level, the Handlebars library is responsible for compiling the hbs language down to HTML:

<p>{{myText}}</p>
<!-- compiles down to: -->
<p>Hello world!</p>

Ember and HTMLBars then builds on top of this, adding useful keywords like action, mut, get, and hash. In fact, all the familiar keywords you’ve been using (everything from each to component) are actually HTMLBars helpers under the hood!

Ember Helpers operate at a higher level compared to HTMLBars helpers, but can also be used as a way to let you create new keywords in Ember, effectively allowing you to extend templating with custom behavior.

It depends

More experienced or conservative developers might see this as a red flag: while making this framework construct available to end-users is useful, it can also open up potential for abuse.

For example, in Elixir, macros can be used to extend the language, but aren’t recommended unless you really need to. In fact, this has been informally codified in the excellent Metaprogramming Elixir book by Chris McCord — “Rule 1: Don’t Write Macros”.

Fortunately, helpers aren’t quite as powerful as Elixir macros, and play an important role in the Ember programming model. Unlike a macro, which lets you reach down to the AST, using an Ember helper to extend presentational logic is OK as long as we don’t abuse it, and that distinction is where experience comes into play. So use helpers responsibly.

Get your logic off my lawn

Some people may feel uneasy using addons containing helpers because of the misconception that it introduces too much logic in their templates, and that they prefer to keep their templates logic-free.

As a best practice, we should strive not to have complicated logic in our templates, and when your sub-expression looks like this:

{{#unless (or (and (gte value 0) (lt value 0.0001))
              (and (lt value 0) (not allowNegativeResults)))}}
  ...
{{/unless}}

It’s a sign that you’re better off using a computed property.

On the other hand, keeping your templates 100% logic-free is really hard — you’re likely already using a logical helper like if/else or unless. It can be easy to lose sight of the fact that the amount of logic in your template lies on a spectrum, and is not a strict dichotomy.

Back to the future

ember-composable-helpers doesn’t significantly increase the amount of logic in your templates — in fact, if used correctly, it encapsulates presentational logic within these helpers, and in many cases can help you eliminate now redundant code in your Components or Controllers.

For example, you might have written something like this in your app:

import Ember from 'ember';

const {
  Component,
  computed: { filterBy, setDiff },
  set
} = Ember;

export default Component.extend({
  activeEmployees: filterBy('employees', 'isActive'),
  inactiveEmployees: setDiff('employees', 'activeEmployees')
});

It’s quite common to have “intermediary” CPs in your Component that you then use in some other CP. Using ember-composable-helpers lets you compose that directly in the template, where the intent becomes incredibly clear:

<h2>Active Employees</h2>
{{#each (filter-by "isActive" employees) as |employee|}}
  {{employee.name}} is active!
{{/each}}

<h2>Inactive Employees</h2>
{{#each (reject-by "isActive" employees) as |employee|}}
  {{employee.name}} is inactive!
{{/each}}

You can think of a composable helper as a kind of computed property macro that you can use and compose directly in your template. And since you can compose sub-expressions in Ember, these can become powerful constructs to reduce boilerplate code in your application.

With that said, remember not to get too carried away with deeply nesting helpers!

The Principle of Least Power

Also known as the Rule of Least Power, this principle can be generally applied as:

Given a choice of solutions, pick the least powerful solution capable of solving your problem. (source)

This rule originated in 2006, from a W3C TAG Finding written by Tim Berners-Lee and Noah Mendelsohn.

Computer Science in the 1960s to 80s spent a lot of effort making languages which were as powerful as possible. Nowadays we have to appreciate the reasons for picking not the most powerful solution but the least powerful. The reason for this is that the less powerful the language, the more you can do with the data stored in that language. If you write it in a simple declarative from, anyone can write a program to analyze it in many ways.

This principle is one of the core ideas that drives Ember and its adoption of Handlebars / HTMLBars over something infinitely more complex in the form of React’s JSX.

This principle is the same reason why you wouldn’t write an eval helper and insert arbitrary JavaScript into your templates. You could, but should you?

Exercise best judgment

As with all programming tools, it’s important to exercise best judgment and use them responsibly.

Just because you can do something doesn’t mean that you should.

A well written view layer means that templates should be as declarative as possible (communicate intent clearly), and not that we should avoid logic altogether. That said, we’re not advocating for moving all your logic into your template — again, it’s not a dichotomy, but a spectrum.

If you’d like to see how the addon is being used, Katherin Siracusa wrote an excellent blog post about how she uses ember-composable-helpers at AlphaSights:

This pattern, of performing some significant, data-changing action and subsequently performing a more ancillary, short-term state-like action, keeps arising in our application. Using […] composable-helpers, we can take care of this in a fairly straightforward way, without much duplication and without having to worry about unintended side effects.

You can also join in the discussion on our Slack channel #e-composable-helpers.

As always, thanks for reading!

Route Closure Actions in Ember.js

Thu, 21 Apr 2016 17:08:25 GMT

In my previous post, I wrote about moving singleton state in Controllers into Services that back components. This means being able to lighten the responsibility of Controllers in your application, and in some cases even remove them completely. However, a common pain point that remains for many is that it isn’t really clear what should live on a Controller, if anything.

(No, they’re not)

Locks has written an excellent blog post on this sometimes controversial topic, and I expanded upon it a little in my podcast episode with Ember Weekend. Erik Hanchett also did a video demo showcasing what I mentioned:

Basically, you still require a Controller if you use query parameters, and in certain cases of bubbling actions.

One reason that is commonly suggested as an argument for using Controllers is that when Routable Components land, it would be a simple rename from Controller to Component. However, if you’ve read my earlier post and listened to the podcast / watched the video above, you’ll know that Routable Components are stateless like ordinary Ember Components. Controllers, on the other hand, are stateful, which means that the transition won’t be so simple.

That said, I wouldn’t go out of your way to creatively avoid using Controllers, and would only remove them if it makes sense to do so. You can ease the transition by extracting your stateful logic into a service, and leaving the stateless logic in your Controller (or Component).

Sending closure actions directly to the route

Closure actions are probably one of my favorite additions to Ember. Instead of casting string actions into the void and praying that something is listening, we can instead use an action like we would any other JavaScript function. This means that we can do useful things like curry arguments, utilize return values, and all of the other good stuff we expect from a regular JS function call.

For example, the following action is implicit in that you have no idea where the action actually lives — it could be on a component, controller or route.

{{! where does `myAction` live? }}
<button {{action "myAction"}}>Do it</button>

Unfortunately, Ember’s in a bit of an awkward transition phase right now. Without bringing in an addon (or making a custom helper), it’s not possible to use a closure action directly from the route — it would have to be defined on the Controller.

If you wanted to remove Controllers from your application, then you would have to resort to using string based actions instead of closure actions. This seems like a lose-lose situation, so I worked together with rwjblue to turn his jsbin spike into a working addon.

ember-route-action-helper lets you use closure actions defined on the route in your templates, meaning that many Controllers that only exist to implement actions can now be removed. You can install it today with:

ember install ember-route-action-helper

And to use it, you can just use route-action in place of action inside of your route’s template, like so:

foo/template.hbs

{{foo-bar click=(route-action "updateFoo" "Hello" "world")}}

This addon gives you all the goodness of closure actions, and is a great way of taking steps to future proof your Ember application. When Routable Components do land, and actions work correctly, then upgrading your app simply becomes a search and replace for s/route-action/action.

Power up your Handlebars templates with Helpers

Helpers are a really nice way of extracting utility functions that you can use in your application. You can create class based Helpers, like ember-route-action-helper, or simple pure-function ones using Helper.helper like the one used in ember-toggle-helper.

Pure-function helpers are simple to grok and understand, so a look at addons like ember-truth-helpers is sufficient to understand them.

ember-route-action-helper uses the class based implementation, which must define a compute method. This is then invoked every time one of the positional arguments to the helper changes.

Under the hood, the route-action helper retrieves the router from the application instance as a computed property, then locates the function reference from the currently active routes:

function getRouteWithAction(router, actionName) {
  let handler = emberArray(getRoutes(router)).find((route) => {
    // find the route with the action
  });

  return { action, handler };
}

The action and the handler (route) is then returned, and wrapped with a closure action, which allows us to do all the nice stuff we expect from any other closure action in Ember. By returning a function in a helper, you can essentially “decorate” the action helper with some custom functionality.

compute([actionName, ...params]) {
  let action = function(...invocationArgs) {
    let args = params.concat(invocationArgs);
    let { action, handler } = getRouteWithAction(router, actionName);

    return run.join(handler, action, ...args);
  };

  // return the closure action
}

And because Helper classes are just like any other class in Ember, you can do the usual things like inject services, define computed properties, and so on. Here’s a contrived example:

import Ember from 'ember';

const {
  inject: { service },
  Helper,
  observer,
  get
} = Ember;

export default Helper.extend({
  session: service('session'),

  compute([shoe]) {
    return parseInt(get(this, 'session.currentUser.shoeSize')) === parseInt(get(shoe, 'size'));
  },

  onShoeSizeChange: observer('session.currentUser.shoeSize', function() {
    this.recompute();
  })
});

The simplified Helper class was introduced in 1.13, and are an excellent addition to Ember. In my next post, I’ll talk a little bit more about them and how we can use them to replace certain CPs.

Until next time, thanks for reading!

Warning — Breaking Changes

Wed, 13 Jan 2016 01:16:06 GMT

In the world of software releases, programmers call a significant change in existing behavior a breaking change. Typically, this means that upgrading that library will break something that already works.

As someone who fell in love with programming and made it a career despite not having formal education in it, I feel incredibly fortunate. I wake up each day thankful for the opportunities I’ve been given — a job I love, a roof over my head, food and water, and many of the luxuries and privileges life has to offer.

2015 was a year of remarkable change for me —I took up a new job at DockYard, moved for the second time in my life to a new country, conquered my greatest fear (public speaking) at EmberConf, and adopted an adorable sweetheart. Writing on this blog has been very rewarding — my posts have been read almost 70,000 times since its inception in September 2014. It’s perhaps the best thing I’ve done for my programming career, and I don’t intend to stop.

Moving to America was particularly tough for me. I’m even further from my family and friends, I broke up with my boyfriend, and despite the things I’ve accomplished in the face of my relative inexperience, I still feel empty.

Upgrading software that contains breaking changes involves fixing something that already works. Depending on the degree to which you relied on it, upgrading can sometimes be a painful process.

Just like software, these changes have been painful, but my life has improved significantly since moving here. I’m grateful for the opportunities DockYard has thrown my way. I’m not exaggerating, but it’s safe to say this is by far the best job I’ve had, and I hope I stay here for a long time.

“How are you doing?”

When I think about it, I’m unhappy because I feel lonely, and because I’m so far away from the friends and family I’ve known for so long. Perhaps it’s the looming Boston winter that’s getting to me, but I don’t have anything else to be unhappy about. Don’t get me wrong, I love my alone time, but too much of a good thing can make you sick.

To a lonely person, asking them how they’re doing can mean a lot.

I’m not the only lonely and unhappy person out there — it wouldn’t be far-fetched to say that there are many like me, even the ones who appear to have their life and career together.

If you get the chance, ask them how they’re doing. They might come across as cold at first, but perhaps with enough warmth in their life, these breaking changes won’t be so painful anymore.

With that said, ultimately my life has improved a lot, and I guess experiencing loneliness and making sacrifices are just facets of growing up that I’ll have to learn how to deal with.

This March, I’m fortunate enough to be speaking at EmberConf once again. I hope I’ll see you there — be sure to say hello!

Happy new year,

Lauren

Ember.js — Goodbye MVC

Thu, 03 Dec 2015 16:49:32 GMT

At EmberConf 2015, Yehuda Katz and Tom Dale announced the arrival of certain changes to Ember 2. Most notably, the routable components RFC attracted a lot of attention because of its proposal to deprecate and eventually remove controllers. Naturally, this was alarming to many existing Ember users, especially since Ember and Sproutcore have always been client-side MVC frameworks.

Goodbye MVC

It is no secret that many new Ember 2 conventions and changes have direct influence from React and Flux (a pattern for data flow in React apps). What Flux calls the “unidirectional data flow” is what we call “Data down, actions up” (DDAU) in Ember.

DDAU avoids the traditional client-side MVC pattern in favor of a single flow of data (hence unidirectional), which makes apps easier to reason about, and improves their performance. The fundamental problem with MVC is revealed as your application grows larger and more complex — cascading updates and implicit dependencies lead to a tangled mess and unpredictability. Updating one object leads to another changing, which in turn triggers more changes, and ultimately makes maintaining your application a frustrating experience.

This work is licensed under a Creative Commons Attribution 4.0 International License.

In the DDAU pattern, data flows one-way and there are no two-way bindings. Different parts of your application can remain highly decoupled and predictable, which means you will always know the source of an object’s change. If you’ve read my post on functional programming and the observer effect, you’ll understand why it’s important to keep your components free from side effects.

Instead of spending time cobbling together your own makeshift framework with a dozen micro-libraries and bike-shedding on the best way to implement a feature, using Ember means instant productivity and quick developer on-boarding. Combined with the DDAU pattern and the Glimmer rendering engine, Ember developers have both productivity and performance out of the box.

Preparing your application for DDAU

When routable components land, controllers will be deprecated and removed. Controllers and views have always been confusing for new Ember users, and “80% of their use cases were to do something that was fundamentally a component” (watch Yehuda and Tom explain more in this video).

Since Ember components aren’t singletons, they will be torn down and re-rendered in an optimized fashion when Glimmer deems necessary. How then to handle state persistence when controllers go away?

For example, you might have some property on your controller that holds on to state that you would like to preserve throughout the app. To do so in Ember 2 (and today), we can remove that controller property in favor of “service-backed components”. The service will hold on to singleton component state, and explicitly injected only where necessary. Because services are powerful and can be easily abused, I’ll talk more about it at the end of this post.

Implementing service-backed components

In the following example, I’ll demonstrate how you can use services and one-way bindings today. You can follow along below as well as check out the demo.

Our little application consists of a couple of checkboxes for selecting animals. This selection needs to persist across different routes, and restore state when returning back to the route. All we need is to define a simple service that holds state for the selected items, and then inject it into the routable component.

In the route’s template, we can just render the injected service’s state using the each helper.

animals/index.hbs

<div class="row">
  <div class="col-md-3">
    <h2>Select Animals</h2>

    {{checkbox-group
        group=animals
        selectedItems=checkboxGroup.selectedItems
        check=(action "check")
    }}
  </div>

  <div class="col-md-9">
    <h3>Selected Animals</h3>
    <table class="table table-bordered">
      <thead>
        <tr>
          <th>ID</th>
          <th>Species</th>
          <th>Name</th>
        </tr>
      </thead>

      <tbody>
        {{#each checkboxGroup.selectedItems as |animal|}}
          <tr>
            <td>{{animal.id}}</td>
            <td>{{animal.species}}</td>
            <td>{{animal.name}}</td>
          </tr>
        {{/each}}
      </tbody>
    </table>
  </div>
</div>

In our controller or routable component, we inject the service and define the action for handling the checked animal. The service’s bag of state is then passed into the component, keeping it as pure as possible. Although you could have just injected the service into the component, doing it this way makes things more explicit and allows the component to be decoupled from the service.

animals/controller.js

import Ember from 'ember';

const { inject: { service }, Controller } = Ember;
const OPERATION_MAP = {
  true: 'addObject',
  false: 'removeObject'
};

export default Controller.extend({
  checkboxGroup: service(),

  // In the future, actions will be defined in the route and passed into the
  // routable component as `attributes`.
  actions: {
    check(group, item, isChecked) {
      return group[OPERATION_MAP[isChecked]](item);
    }
  }
});

As mentioned, the service itself is simple. We can define more complex behavior later, but the underlying persistence for its state is just a JavaScript array.

checkbox-group/service.js

import Ember from 'ember';

const { Service } = Ember;

export default Service.extend({
  init() {
    this._super(...arguments);
    this.selectedItems = [];
  }
});

Because our behavior is simple, we don’t need to define a sub-classed component in this example. The check action is passed in from the routable component / controller, so using closure actions in the component’s template means that we don’t have to cast sendActions into the void.

In our component’s template, we make use of small, composable helpers. These helpers are just simple JavaScript functions under the hood, and because they have return values, we can use them as Handlebars sub-expressions where we might have once defined a computed property.

The contains helper doesn’t ship with Ember, but the function itself is one line of code. There are a bunch of useful addons that add helpers such as these to your application — for example, ember-truth-helpers is an addon I find myself using in almost all my apps.

checkbox-group/template.hbs

{{#each group as |item|}}
  <div class="checkbox">
    <label for={{concat "item-" item.id}}>
      {{one-way-input
          id=(concat "item-" item.id)
          class="checkbox"
          type="checkbox"
          checked=(contains selectedItems item)
          update=(action this.attrs.check selectedItems item)
      }} {{item.name}} <span class="label label-default">{{item.species}}</span>
    </label>
  </div>
{{/each}}

As mentioned in my previous post, the ember-one-way-input addon is an easy way to start using one-way bindings today.

I hope this simple example illustrates how you can build maintainable and performant apps with some of my favorite features of Ember — helpers, closure actions, components, and one-way bindings.

A word of caution about Services

As the cliché goes, “with great power…”. Because services in Ember are singletons, it becomes tempting to make multiple services and inject them everywhere.

If your main reason for creating a service is to use it as a global, that is generally a code smell because dependencies become implicit (we learned earlier that this is a bad thing) and parts of your application become tightly coupled. Instead, expose data and actions via interfaces to keep your code decoupled and explicit. Remember the Principle of Least Power, and only use a service when strictly necessary!

So when should I use a Service?

I like this Stack Overflow answer on when you should use a singleton. Essentially, you should only use one when you can only have a single instance throughout your application. For example, a shopping cart, flash messages, or activity feed could be great candidates for a service.

Thanks for reading! In my next post in this series, we’ll explore other advanced techniques for the DDAU pattern.

Until next time,

Lauren

Ember.js — Functional Programming and the Observer Effect

Mon, 16 Nov 2015 16:06:28 GMT

My awesome colleagues have written about patterns and best practices we use at DockYard, covering everything from the Ember Object model and better acceptance tests, to native inputs and closure actions.

Today, I’d like to write about something that is close to all our hearts — observers; and a topic I think about a lot — functional programming (FP). I’d like to take you through a tour of refactoring away from observers in your application and freeing yourself from the shackles of the “observer effect”. Let’s get started!

Side effects wreck projects

In science, the term “observer effect” refers to the changes that are effected on some phenomenon simply by observing it. This is often because of instruments that alter the state of what they observe in some manner.

Sound familiar? Funnily enough, the same effect can probably be found in your Ember application if you use observers. For reasons we’ll cover in this post, observers are an anti-pattern and should be avoided, as it makes it difficult to reason about and debug your application.

Difficult to reason about? ¯\_(ツ)_/¯

“Difficult to reason about” is a term that is commonly thrown around — but what exactly does it mean? Informally, it means being able to tell what a program will do just by looking at its code. That is, running the program should not lead to unexpected surprises. We strive to make our applications easy to reason about because it leads to more maintainable code that is easier to debug and test.

That is, running the program should not lead to unexpected surprises.

Since JavaScript isn’t a purely functional language, it does not enforce immutability by default. Its mutable data structures can sometimes lead to surprising and unintuitive results (making some JavaScript applications difficult to reason about), so various attempts have been made to introduce immutability to the language.

For example, ClojureScript and Elm are functional languages that compile down to JavaScript. Mori and immutable.js are also excellent libraries that provide immutable data structures you can use in vanilla JavaScript. These tools bring in bits of FP philosophy into JavaScript applications, and have become increasingly popular in front-end development thanks to the introduction of React and the Flux pattern.

The “rise” of Functional Programming in front end development

FP is not a new programming paradigm — it’s been around for a while since the introduction of LISP in the late 50s. However, it’s only in recent times that we’ve seen FP languages become more mainstream, most notably with Elixir, which combines the elegance and productivity of Ruby with the performance of the Erlang VM.

The combination of Ember’s conventions (over configuration), Glimmer, and DDAU means that just like Elixir, Ember developers too can find the sweet spot of having both productivity and performance.

Why is FP useful for building front end applications? React taught us that it is surprisingly cheap to diff the changes on the DOM, and to perform a series of updates to sync the DOM with its virtual representation. In other words, React made its render function a pure one (one of the core principles of FP) — you always get the same output (HTML) for a given input (state).

With the Flux pattern, that is taken a step further and the entire application is treated as a pure function — for a given serialized state, we can predictably render the same output each time. This has allowed Flux implementations like Redux the ability to have a “time traveling debugger”, which is only possible when you model your architecture with a FP paradigm.

Object.observe is not the answer

These philosophies have had resounding success, so much so that Object.observe was withdrawn from TC39. All this means is that observing property changes are no longer the best way of building web applications, and Ember in general is moving in that direction with it’s “Data Down, Actions Up” (DDAU) philosophy.

In 1.13.x, Glimmer landed — it is Ember’s new rendering engine based on the same pure render semantics, and gives us fast, idempotent re-renders. The combination of Ember’s conventions (over configuration), Glimmer, and DDAU means that just like Elixir, Ember developers too can find the sweet spot of having both productivity and performance.

Data Down, Actions Up

Although you could bring in immutable data structures into your application (a topic for a future post!), that alone wouldn’t be enough. We should also strive to make our business logic as pure (free of side effects) as possible. Of course, it wouldn’t be possible to make everything pure, as web applications inherently involve mutation (i.e. updating a user record), but it is beneficial to explicitly know and isolate the functions in your app that do have side effects.

In Ember 2.x, the best way forward is “Data Down, Actions Up”. This means:

One way bindings by default
Explicit closure actions over side effects
Components should not mutate data directly

My colleagues have already written about one way bindings, closure actions and not mutating data in Components, so I will leave you to do further reading in your own time.

Instead, let’s continue the discussion above on how best to refactor away observers in your application, so that we can eliminate or reduce side effects.

Refactoring away observers

Let’s say we have an observer in our application that needs to check a user’s birthday (demo):

birth-day/component.js

import Ember from 'ember';
import moment from 'moment';

const {
  Component,
  computed,
  get,
  set
} = Ember;

export default Component.extend({
  isBirthday: false,
  birthDate: null,

  age: computed('birthDate', {
    get() {
      return moment().diff(moment(get(this, 'birthDate')), 'years');
    }
  }),

  checkBirthday() {
    let today = moment();
    let birthDate = moment(get(this, 'birthDate'));
    let isBirthday = (today.month() === birthDate.month()) &&
      (today.day() === birthDate.day());

    set(this, 'isBirthday', isBirthday);
  },

  init() {
    this._super(...arguments);
    this.addObserver('birthDate', this, this.checkBirthday);
  },

  willDestroy() {
    this.removeObserver('birthDate', this, this.checkBirthday);
  }
});

In the above example, we’re using an observer to set the isBirthday flag if it is the user’s birthday.

birth-day/template.hbs

{{input value=birthDate placeholder="Your birthday"}}

<p>
  You are currently {{age}} years old.
  {{#if isBirthday}}
    Happy birthday!
  {{/if}}
</p>

When you find yourself setting some value (be in on the component, record or somewhere else), you can easily refactor away the observer.

Removing an observer that sets a value on the component

In this scenario, you can simply replace the observer with a CP.

birth-day/component.js

import Ember from 'ember';
import moment from 'moment';

const {
  Component,
  computed,
  get
} = Ember;

export default Component.extend({
  // ...
  isBirthday: computed('birthDate', {
    get() {
      let today = moment();
      let birthDate = moment(get(this, 'birthDate'));

      return (today.month() === birthDate.month()) &&
        (today.day() === birthDate.day());
    }
  })
});

Using component lifecycle hooks

We could also move the input logic out of this component, and use the new component lifecycle hooks to set the isBirthday flag on the component.

birth-day/component.js

import Ember from 'ember';
import moment from 'moment';

const {
  Component,
  computed,
  get
} = Ember;

export default Component.extend({
  birthDate: null,
  today: null,
  isBirthday: false,

  didReceiveAttrs() {
    let isBirthday = this.checkBirthday(
      moment(get(this, 'today')),
      moment(get(this, 'birthDate'))
    );

    set(this, 'isBirthday', isBirthday);
  },

  checkBirthday(today, birthDate)
    return (today.month() === birthDate.month()) &&
      (today.day() === birthDate.day());
  })
});

index/template.hbs

{{one-way-input
    value=user.birthDate
    update=(action (mut user.birthDate))
    placeholder="Your birthday"
}}
{{happy-birthday today=today birthDate=user.birthDate}}

birth-day/template.hbs

<p>
  You are currently {{age}} years old.
  {{#if isBirthday}}
    Happy birthday!
  {{/if}}
</p>

Both approaches let you remove the observer, but the didReceiveAttrs example is slightly more explicit, and transforms the component into a pure one. By limiting the scope of the component, we can easily isolate the origins of data mutations.

Removing an observer that sets a value outside the component

In this situation, let’s say we want to update the user record’s isBirthday flag instead. We can remove the observer by using one way input actions:

By bringing in the ember-one-way-input addon, we can eliminate the coupling of the component to the user record:

birth-day/component.js

import Ember from 'ember';
import moment from 'moment';

const {
  Component,
  computed,
  get
} = Ember;

export default Component.extend({
  // ...
  actions: {
    checkBirthday(birthDate) {
      birthDate = moment(birthDate);
      let today = moment();
      let isBirthday = (today.month() === birthDate.month()) &&
        (today.day() === birthDate.day());

      this.attrs.setIsBirthday(isBirthday);
      this.attrs.setBirthDate(birthDate.toDate());
    }
  }
});

birth-day/template.hbs

{{one-way-input
    value=birthDate
    update=(action "checkBirthday")
    placeholder="Your birthday"
}}

<p>
  You are currently {{age}} years old.
  {{#if isBirthday}}
    Happy birthday!
  {{/if}}
</p>

And then in the Controller:

index/controller.js

import Ember from 'ember';

const { Controller, set } = Ember;

export default Controller.extend({
  actions: {
    setIsBirthday(isBirthday) {
      set(this, 'user.isBirthday', isBirthday);
      user.save();
    },

    setBirthDate(birthDate) {
      set(this, 'user.birthDate', birthDate);
      user.save();
    }
  }
});

index/template.hbs

{{happy-birthday
    setIsBirthday=(action "setIsBirthday")
    setBirthdate=(action "setBirthdate")
    isBirthday=user.isBirthday
    birthDate=user.birthDate
}}

In the above example, we moved the logic for setting the isBirthday flag out of the happy-birthday component into its Controller. The component no longer needs to directly mutate state (an anti-pattern would be to set user.isBirthday directly in the component), and can instead send a closure action up, leaving the Controller to decide how to handle the actions. Data now flows down to the Component, and any changes to the input sends actions back up.

Who should use observers?

If observers are so terrible, why are they in Ember? According to Stefan Penner, observers are used by the framework itself as a low level primitive, so that you don’t need to use them yourself. So unless you’re working on a PR for Ember.js, stay away from observers.

Thanks for reading!

I hope you’ve enjoyed this post! It’s been a while since my last one so I do apologize. I hope to start writing shorter articles again more frequently — if you have suggestions for topics, please feel free to DM me on Slack or tweet me!

Until next time,

Lauren

Applying the Adapter Pattern for Analytics in Ember.js Apps

Fri, 07 Aug 2015 18:12:11 GMT

At DockYard, most (if not all) Ember apps we build for our clients require analytics in some form or other. For many of these apps, including the Google Analytics tracking script is sufficient. However, we’ve begun to notice an increased interest in other services such as Mixpanel or Kissmetrics for more data minded clients.

Including multiple services (typically we see about 3–5 different analytics in use) with different APIs leads to code duplication, which is less than ideal and generally a maintenance nightmare. I don’t know about you, but deleting repetitive code is one of my favorite things to do — so Michael and I set out to build an Ember addon that would apply the adapter pattern to analytics.

In this post, we’ll explore what the adapter pattern is, what it gives us, and demonstrate how to implement it to enable one API for orchestrating multiple analytics services.

Introducing the ember-metrics addon

To install the addon:

$ ember install ember-metrics

The ember-metrics addon adds a simple metrics service and customized LinkComponent to your app that makes it simple to send data to multiple analytics services without having to implement a new API each time.

Using this addon, you can easily use bundled adapters for various analytics services, and one API to track events, page views, and more. When you decide to add another analytics service to your stack, all you need to do is add it to your configuration, and that’s it.

With this addon, we wanted to make it super simple to write your own adapters for other analytics services too, so we set out to make it extensible and easily tested.

What is the Adapter Pattern?

I heard you like adapters

In a broad sense, the adapter pattern is about adapting between class and objects. Like its real world counterpart, the adapter is used as an interface, or bridge, between two objects.

In the case of analytics, this is an excellent pattern for us to implement, because these services all have different APIs, but very similar intent. For example, to send an event to Google Analytics, you would use the analytics.js library like so:

/**
 * Where:
 * button is the category
 * click is the action
 * nav buttons is the label
 * 4 is the value
*/
ga('send', 'event', 'button', 'click', 'nav buttons', 4);

While in Mixpanel, you would track the same event like this:

mixpanel.track('Clicked Nav Button', { value: 4 });

And with Kissmetrics:

_kmq.push(['record', 'Clicked Nav Button', { value: 4 }]);

As you can probably tell, this gets repetitive really quickly, and becomes hard to maintain when your boss or client wants to update something as simple as the event name across these services.

Applying the Adapter Pattern

Diagram from https://sourcemaking.com/design_patterns/adapter

We generally have a few players in the adapter pattern: the client, the adapter (or wrapper), and the adaptee.

For ember-metrics, the client is our Ember.Service, the adapter is the adapter created for each analytics service, and the adaptee is the analytics library’s API.

Each analytics service has its own adapter that implements a standard contract to impedance match the analytics library’s API to the Ember.Service that is responsible for conducting all of the analytics in unison.

Using ember-metrics

The addon is first setup by configuring it in config/environment, then injected into any Object registered in the container that you wish to track.

module.exports = function(environment) {
  var ENV = {
    metricsAdapters: [
      { name: 'GoogleAnalytics', config: { id: 'UA-XXXX-Y' } },
      { name: 'Mixpanel', config: { token: 'xxx' } }
    ]
  }
}

Then, you can call a trackPage event across all your analytics services like so, using the metrics service:

import Ember from 'ember';

export default Ember.Route.extend({
  metrics: inject.service(),

  activate() {
    this._trackPage();
  },

  _trackPage() {
    run.scheduleOnce('afterRender', this, () => {
      const page = document.location.href;
      const title = this.routeName;

      get(this, 'metrics').trackPage({ page, title });
    });
  }
});

If you wish to only call a single service, just specify its name as the first argument:

// only invokes the `trackPage` method on the `GoogleAnalyticsAdapter`
metrics.trackPage('GoogleAnalytics', { title: 'My Awesome App' });

This is clearly a much cleaner implementation, as we can now use one API to invoke across all services we want to use in our app.

Implementing the Adapter Pattern in ember-metrics

The service metrics is the heart of the addon, and is responsible for orchestrating event tracking across all analytics that have been activated.

Setting up addon configuration

A simple pattern for passing configuration from the consuming app’s config/environment to the addon is through an initializer:

import config from '../config/environment';

export function initialize(_container, application) {
  const { metricsAdapters = {} } = config;

  application.register('config:metrics', metricsAdapters, { instantiate: false });
  application.inject('service:metrics', 'metricsAdapters', 'config:metrics');
}

export default {
  name: 'metrics',
  initialize
};

This lets us access the configuration POJO from within the metrics service by retrieving the metricsAdapter property when the service is created.

import Ember from 'ember';

export default Ember.Service.extend({
  _adapters: {},

  init() {
    const adapters = Ember.getWithDefault(this, 'metricsAdapters', Ember.A([]));
    this._super(...arguments);
    this.activateAdapters(adapters);
  },

  activateAdapters(adapterOptions = []) {
    const cachedAdapters = Ember.get(this, '_adapters');
    const activatedAdapters = {};

    adapterOptions.forEach((adapterOption) => {
      const { name } = adapterOption;
      let adapter;

      if (cachedAdapters[name]) {
        Ember.warn(`[ember-metrics] Metrics adapter ${name} has already been activated.`);
        adapter = cachedAdapters[name];
      } else {
        adapter = this._activateAdapter(adapterOption);
      }

      Ember.set(activatedAdapters, name, adapter);
    });

    return Ember.set(this, '_adapters', activatedAdapters);
  }
});

With the retrieved configuration, we then call the service’s activateAdapters method in order to retrieve the adapter(s) from the addon or locally, then caching them in the service so they can be looked up later easily.

Activating an adapter simply calls create on the looked up adapter (which inherits from Ember.Object) and passes along any analytics specific configuration such as API keys.

_activateAdapter(adapterOption = {}) {
  const metrics = this;
  const { name, config } = adapterOption;

  const Adapter = this._lookupAdapter(name);
  assert(`[ember-metrics] Could not find metrics adapter ${name}.`, Adapter);

  return Adapter.create({ metrics, config });
}

Because we’ve also implemented caching, we can safely call activateAdapters without having to re-instantiate already activated adapters, which allows us to defer the initialization of these analytics if (for example) we need to dynamically retrieve a property from one of our models:

import Ember from 'ember';

export default Ember.Route.extend({
  metrics: Ember.inject.service(),
  afterModel(model) {
    const metrics = Ember.get(this, 'metrics');
    const id = Ember.get(model, 'googleAnalyticsKey');

    metrics.activateAdapters([
      { name: 'GoogleAnalytics', config: { id } }
    ]);
  }
});

Leveraging the container and resolver

Then, leveraging the Ember container and conventions around the ember-resolver, we can lookup adapters from the addon first, and then fallback to locally created adapters.

_lookupAdapter(adapterName = '') {
  const container = Ember.get(this, 'container');

  if (isNone(container)) {
    return;
  }

  const dasherizedAdapterName = dasherize(adapterName);
  const availableAdapter = container.lookupFactory(`ember-metrics@metrics-adapter:${dasherizedAdapterName}`);
  const localAdapter = container.lookupFactory(`metrics-adapter:${dasherizedAdapterName}`);
  const adapter = availableAdapter ? availableAdapter : localAdapter;

  return adapter;
}

This is done through looking up the adapter factory with container.lookupFactory, and passing in the correct name that the resolver can understand. For example, we can look up adapters from the addon by using the following lookup pattern:

name-space?@folder-name:file-name

Where name-space (and the following @ symbol) is optional, if looking up from within the app. One thing to note is that the ‘folder name’ is usually determined by the singular form. For example, you would lookup the metrics service from the container like so:

const metricsInstance = container.lookup('ember-metrics@service:metrics');

If you’re wondering how the resolver maps this string to the actual files, you only need to type requirejs.entries into the developer console while in an Ember app. This returns all the entries that have been exported by requirejs. For example, here are some of the entries from the DockYard website:

To lookup the ember-wormhole component class from the application container, you would use:

container.lookupFactory('ember-wormhole@component:ember-wormhole');

…which returns what you’d expect.

Invoking adapter methods from the service

Now that our service can access both local and addon adapters, we can invoke methods across activated adapters like so:

identify(...args) {
  this.invoke('identify', ...args);
},

alias(...args) {
  this.invoke('alias', ...args);
},

trackEvent(...args) {
  this.invoke('trackEvent', ...args);
},

trackPage(...args) {
  this.invoke('trackPage', ...args);
},

invoke(methodName, ...args) {
  const adaptersObj = Ember.get(this, '_adapters');
  const adapterNames = Object.keys(adaptersObj);

  const adapters = adapterNames.map((adapterName) => {
    return Ember.get(adaptersObj, adapterName);
  });

  if (args.length > 1) {
    let [ adapterName, options ] = args;
    const adapter = Ember.get(adaptersObj, adapterName);

    adapter[methodName](options);
  } else {
    adapters.forEach((adapter) => {
      adapter[methodName](...args);
    });
  }
}

Creating Adapters for the Addon

With the service implemented, we can now create a base adapter class that all adapters extend from:

/* jshint unused: false */
import Ember from 'ember';
import canUseDOM from '../utils/can-use-dom';

function makeToString(ret) {
  return function() { return ret; };
}

export default Ember.Object.extend({
  init() {
    Ember.assert(`[ember-metrics] ${this.toString()} must implement the init hook!`);
  },

  willDestroy() {
    Ember.assert(`[ember-metrics] ${this.toString()} must implement the willDestroy hook!`);
  },

  toString() {
    const hasToStringExtension = Ember.typeOf(this.toStringExtension) === 'function';
    const extension = hasToStringExtension ? ':' + this.toStringExtension() : '';
    const ret = `ember-metrics@metrics-adapter:${extension}:${Ember.guidFor(this)}`;

    this.toString = makeToString(ret);
    return ret;
  },

  metrics: null,
  config: null,
  identify: Ember.K,
  trackEvent: Ember.K,
  trackPage: Ember.K,
  alias: Ember.K
});

This is mainly so we can assert that the adapter’s init and willDestroy hooks are implemented, and to give it a nicer output in the console through overriding the toString function.

If you’re not already familiar with the Ember Object model, the init method is called whenever an Ember.Object is instantiated through Ember.Object.create().

We can thus rely on this knowledge that init will always be called on object instantiation to pass in configuration to the analytics, and to call its setup. Typically, an analytics service will create a script tag through JavaScript, and asynchronously load its library from some CDN.

Here’s the Google Analytics adapter that’s bundled with the addon:

import Ember from 'ember';
import canUseDOM from '../utils/can-use-dom';
import objectTransforms from '../utils/object-transforms';
import BaseAdapter from './base';

export default BaseAdapter.extend({
  toStringExtension() {
    return 'GoogleAnalytics';
  },

  init() {
    const config = Ember.get(this, 'config');
    const { id } = config;

    Ember.assert(`[ember-metrics] You must pass a valid \`id\` to the ${this.toString()} adapter`, id);

    if (canUseDOM) {
      /* jshint ignore:start */
      (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
        (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
        m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
      })(window,document,'script','//www.google-analytics.com/analytics.js','ga');
      window.ga('create', id, 'auto');
      /* jshint ignore:end */
    }
  },

  trackEvent(options = {}) {
    const compactedOptions = objectTransforms.compact(options);
    const sendEvent = { hitType: 'event' };
    let gaEvent = {};

    for (let key in compactedOptions) {
      const capitalizedKey = Ember.String.capitalize(key);
      gaEvent[`event${capitalizedKey}`] = compactedOptions[key];
    }

    const event = Ember.merge(sendEvent, gaEvent);
    window.ga('send', event);

    return event;
  },

  trackPage(options = {}) {
    const compactedOptions = objectTransforms.compact(options);
    const sendEvent = { hitType: 'pageview' };

    const event = Ember.merge(sendEvent, compactedOptions);
    window.ga('send', event);

    return event;
  },

  willDestroy() {
    Ember.$('script[src*="google-analytics"]').remove();
    delete window.ga;
  }
});

Enhancing the developer experience with blueprints

One of my favorite parts of ember-cli are its generators. Using blueprints, we can easily extend the cli commands to generate new metrics adapters using:

$ ember generate metrics-adapter foo-bar

This creates app/metrics-adapters/foo-bar.js and a unit test at tests/unit/metrics-adapters/foo-bar-test.js. You can take a closer look at these blueprints here.

With these conventions in place, it’s now trivial for consuming app developers to add new adapters to work along side bundled adapters. And when they feel that an adapter they’ve built is ready to be shared with the community, they only need open a pull request to have that adapter included in the addon.

At some point in the future, it would make sense for each adapter to have its own repo and npm module, but to keep things simple, we’ve placed them within the addon.

Thanks for reading!

I hope you’ve learned something about addon creation and the adapter pattern. As always, please direct any comments or criticism to @potetotes.

Until next time,

Lauren

Declarative Breadcrumb Navigation in Ember.js

Mon, 01 Jun 2015 22:48:44 GMT

Breadcrumb navigation isn’t a new concept, in fact, it’s usefulness has been endlessly debated about by UX designers all over. Today, I won’t get into the nitty gritty on whether or not your app should include one, but I’d like to share an addon I built for a project I’m working on that required it.

This is a simple Component that is placed once in your application, and then generates a dynamic breadcrumb by looking up the current route hierarchy. The addon has a simple declarative API, which makes integration with your app super easy.

Let’s dive in!

I will steal your croissant and eat it. Does anyone even read this caption?

Demo & Source

One True God

You can take a look at the demo app to see ember-crumbly in action. What’s cool about it is how little code it takes to add dynamic breadcrumbs to your app, and how declarative it is. The source is on GitHub, as always.

The idea

We work on many Ember apps at DockYard, and one particular client’s project I was working on called for a very dynamic breadcrumb type UI that would respond to changes in the route and model. Before I started actually implementing it, I sketched my plan on paper to see if I could make it nice and declarative instead of manually setting the breadcrumb on each of those route templates.

The Ember Container and currentRouteName

The Component relies mainly on Ember’s container and the current route name. On a high level, the Component is injected with the Application Controller’s currentRouteName prop, then looks up the appropriate route in the Container to check if it has a breadCrumb prop defined. If it does, we display whatever the POJO is, or else we show its route name in the Component.

Intended usage

The goal was to have an API as declarative as the following:

{{bread-crumbs linkable=true outputStyle="foundation"}}

And the route:

foo/route.js

export default Ember.Route.extend({
  breadCrumb: {
    title: 'Animals'
  }
});

We wanted to be able to pass in our own template block too:

{{#bread-crumbs linkable=true as |component route|}}
  {{#if route.title}}
    {{route.title}}
  {{else}}
    {{route.foo}} ({{route.bar}}) ... {{route.baz}}
  {{/if}}
{{/bread-crumbs}}

Let’s see how we can write a component that does just that using some of Ember’s new features.

Injecting the Application Controller

I’ve explained how we inject things in other posts, so I won’t go into detail for the initializer. Ember adds the currentRouteName and currentPath to the Application Controller, so we’ll inject it into our Component so we can extract it.

export function initialize(container, application) {
  application.inject('component:bread-crumbs', 'applicationController', 'controller:application');
}

export default {
  name: 'crumbly',
  initialize
};

Declaring your variables

We typically declare our variables and functions used at the top of each file, to make code easier to read and refactor in the future. For ember-crumbly’s bread-crumbs component, we’re using the usual suspects:

import Ember from 'ember';
import layout from '../templates/components/bread-crumbs';

const get = Ember.get;
const {
  A: emberArray,
  EnumerableUtils,
  Component,
  Logger,
  computed,
  getWithDefault,
  assert,
  typeOf,
  setProperties
} = Ember;

const {
  classify
} = Ember.String;

const {
  map,
  filter
} = EnumerableUtils;

const {
  warn
} = Logger;

You might be wondering why we declare const get = Ember.get; by itself on line 4 — currently there are issues with destructuring { get } and bugs in Esprima, so we do it by itself as temporary workaround.

Component props

Here we set a bunch of default props for the component.

export default Component.extend({
  layout,
  tagName: 'ol',
  linkable: true,
  reverse: false,
  classNameBindings: [ 'breadCrumbClass' ],
  hasBlock: computed.bool('template').readOnly(),
  currentRouteName: computed.readOnly('applicationController.currentRouteName'),

We’ve injected the Application Controller into the component in our initializer, so getting the current route’s name is as simple as setting a computed property macro. We make it readOnly so we don’t set it by accident.

Computing the route hierarchy

Ember’s currentRouteName prop returns the current route hierarchy separated by periods. For example, if you were on /foo/bar/baz, your route would probably be something like foo.bar.baz.index. Knowing this, the goal would be to split the string by the period, and then working out the route name for each of its parts. With the correct route name, we can then lookup the route on the container and extract the breadCrumb POJO we need for our bread-crumb.

  routeHierarchy: computed('currentRouteName', 'reverse', {
    get() {
      const currentRouteName = getWithDefault(this, 'currentRouteName', false);

      assert('[ember-crumbly] Could not find a curent route', currentRouteName);

      const routeNames = this._splitCurrentRouteName(currentRouteName);
      const filteredRouteNames = this._filterIndexRoutes(routeNames);

      const crumbs = this._lookupBreadCrumb(routeNames, filteredRouteNames);
      return this.get('reverse') ? crumbs.reverse() : crumbs;
    },

    set() {
      warn('[ember-crumbly] `routeHierarchy` is read only');
    }
  }),

You’ll notice straight away that we’re using new Ember computed property syntax here. The new syntax allows you to set both getters and setters on your CP, instead of checking argument length like you used to have to do.

Figuring out the route name

First, we split the currentRouteName string into an array, and then filter out any index routes. This is because the string splits into an array with all the parts, so foo/bar/baz would yield ['foo', 'bar', 'baz', 'index'], while we only want the first 3.

  _splitCurrentRouteName(currentRouteName) {
    return currentRouteName.split('.');
  },

  _filterIndexRoutes(routeNames) {
    return filter(routeNames, (name) => {
      return name !== 'index';
    });
  },

Now with the array of parts, we need to piece them together again bit by bit to reconstruct their constituent routes.

Looking up the route on the container

In here, we:

Map over the filtered route names individually
Reconstruct the route name by slicing the original array of route names with the right end argument
Look the reconstructed route name up on the container
Retrieve the breadCrumb POJO, add props to it, and return an Ember Array that our component can iterate over in its template

  _lookupBreadCrumb(routeNames, filteredRouteNames) {
    const defaultLinkable = get(this, 'linkable');
    const breadCrumbs = map(filteredRouteNames, (name, index) => {
      const path = this._guessRoutePath(routeNames, name, index);
      let breadCrumb = this._lookupRoute(path).getWithDefault('breadCrumb', undefined);
      const breadCrumbType = typeOf(breadCrumb);

      if (breadCrumbType === 'undefined') {
        breadCrumb = {
          path,
          linkable: defaultLinkable,
          title: classify(name)
        };
      } else if (breadCrumbType === 'null') {
        return;
      } else {
        setProperties(breadCrumb, {
          path,
          linkable: breadCrumb.hasOwnProperty('linkable') ? breadCrumb.linkable : defaultLinkable
        });
      }

      return breadCrumb;
    });

    return emberArray(filter(breadCrumbs, (breadCrumb) => {
      return typeOf(breadCrumb) !== 'undefined';
    }));
  }

Reconstructing the route name

Each time map runs in the previous method, we get a single piece of the route name, e.g. bar. We know that its correct route name is foo.bar, so we can slice the original array with the map’s index argument to piece those bits together. When we start with the first piece (foo), we know that we need to look up foo.index so that we can generate the correct link-to, so we check for that.

  _guessRoutePath(routeNames, name, index) {
    const routes = routeNames.slice(0, index + 1);

    if (routes.length === 1) {
      return `${name}.index`;
    } else {
      return routes.join('.');
    }
  },

Now that we have the correct route name for each path, we can look up the actual route object on the Container while we map over the filtered route names.

Looking up the route on the Container

The Ember Container (basically how Ember keeps track of all its different objects) isn’t well documented because it is originally intended to be private API. However, many addons and apps make use of it to do certain things, and this one is no exception. There is an RFC on the table with reforming the Registry and Container, so this might have to be changed in the future. For now, we can still get the Container from the Component, and then use its lookup('type:name') method to find the route.

  _lookupRoute(routeName) {
    const container = get(this, 'container');
    const route = container.lookup(`route:${routeName}`);
    assert(`[ember-crumbly] \`route:${routeName}\` was not found`, route);

    return route;
  },

With the route object in hand, we can then easily extract the breadCrumb POJO we define on our routes.

let breadCrumb = this._lookupRoute(path).getWithDefault('breadCrumb', undefined);
const breadCrumbType = typeOf(breadCrumb);

if (breadCrumbType === 'undefined') {
  breadCrumb = {
    path,
    linkable: defaultLinkable,
    title: classify(name)
  };
} else if (breadCrumbType === 'null') {
  return;
} else {
  setProperties(breadCrumb, {
    path,
    linkable: breadCrumb.hasOwnProperty('linkable') ? breadCrumb.linkable : defaultLinkable
  });
}

return breadCrumb;

In certain scenarios, you might want to opt-out of displaying a specific route in the breadcrumb. We allow that by setting breadCrumb: null inside of that route. If no breadCrumb POJO is found, we set the title to be the route’s capitalized name by default, and if we do find one, we simply add the path and linkable keys to it.

Finally, we return an Ember Array so that the resulting array is iterable in the template, and filter out any undefined breadcrumbs.

return emberArray(filter(breadCrumbs, (breadCrumb) => {
  return typeOf(breadCrumb) !== 'undefined';
}));

With the logic done, let’s look at our somewhat complicated template to handle all the different uses!

Yo dawg, I heard you like conditional logic in your templates

Because we want to handle both the inline and block form of the Component, as well as the ability to make each route linkable, the template does get a little ugly. Fortunately, this is still manageable and is hidden from our consuming users, so that’s our problem.

{{#each routeHierarchy as |route|}}
  <li class={{crumbClass}}>
    {{#if hasBlock}}
      {{#if route.linkable}}
        {{#link-to route.path}}
          {{yield this route}}
        {{/link-to}}
      {{else}}
        {{yield this route}}
      {{/if}}
    {{else}}
      {{#if route.linkable}}
        {{#link-to route.path}}
          {{route.title}}
        {{/link-to}}
      {{else}}
        {{route.title}}
      {{/if}}
    {{/if}}
  </li>
{{/each}}

And that’s done!

Thanks for reading!

This has been yet another long post, I hope I’ve managed to explain my ideas well and maybe show you a new thing or two about Ember.

Until next time,

Lauren / DockYard

Creating an Ember CLI addon — Detecting Ember.js Components Entering or Leaving the Viewport

Fri, 17 Apr 2015 23:02:16 GMT

I wrote a post last year about how I made an Ember Mixin that would let Ember Components or Views know if their DOM element had entered or left the viewport. If you’re unfamiliar with the getBoundingClientRect API or the approach in general (for determining if an element is in the viewport), please have a read of that post first!

This time, I want to talk about how I improved the original Mixin to use the requestAnimationFrame API for improved performance at close to 60FPS, as well as to go through the process of creating a simple ember-cli addon. Because certain browsers (mainly IE) don’t support rAF, we’ll also setup an automatic fallback to using the Ember run loop method I used in my previous post.

Let’s get started!

Demo App

Featuring Brian from DockYard ☺

I made a simple demo app to demonstrate how you might use the Mixin. The goal for this addon was to allow you to easily style or do something with Components/Views when they enter or leave the viewport. For example, you could easily use this Mixin to build a lazy loader for images, or even for triggering animations. Using this Mixin, you won’t need to bring a jQuery plugin and can instead rely on a highly performant ember-cli addon.

Installing the addon

If you’re using ember-cli and want to use the addon, you can install it with:

$ ember install ember-in-viewport

The source for the addon is available at dockyard/ember-in-viewport.

Creating your first ember-cli addon

I’m going to walk through this post as if I was creating the ember-in-viewport addon, so I’ll be using that name from here on.

With ember-cli, creating a new addon is just one command away:

$ ember addon ember-in-viewport

This generates a new folder structure with the same name as your addon. Before we dive into the addon logic, let’s get a few housekeeping items out of the way.

Updating manifests

package.json is the manifest for your ember-cli addon that does many things with npm. Because this is quite basic, I won’t go into any details here, but you’ll want to update your addon’s name, description, repository, author name and keywords as relevant to your addon. If you care at all about scores on Ember Observer, you’ll want to make sure these are filled out correctly because they do affect scores! They also help with finding your addon on npm, so it doesn’t hurt to fill these out from the start.

For this addon, since we’re not using ember-data, we’re going to delete that line in package.json as well as bower.json.

Adding an ember-try config

ember-try is a wonderful ember-cli addon by @katiegengler that helps you test against multiple bower dependencies such as ember and ember-data. This means you’ll be able to test your addon to verify if it works on other versions, which is a nice thing to do as an addon author! For ember-in-viewport, we test against ember 1.11.1, release, beta and canary channels.

With that out of the way, we can start writing the improved logic for the addon.

Rewriting the In Viewport Mixin

The Mixin still uses the same method for determining if a DOM element is in the viewport, using getBoundingClientRect and the window’s innerHeight and innerWidth.

First, let’s create a new Mixin using ember-cli:

$ ember g mixin in-viewport

This creates the appropriate files inside of /addon, which is the main folder for your addon’s logic. This folder won’t be merged with the consuming ember application’s tree (unlike the /app folder). For this addon, we want our users to import the mixin directly from the addon itself, so we’ll delete the folder that was generated inside of /app, and update the generated tests to import the right file.

Importing modules and utils

import Ember from 'ember';
import canUseDOM from 'ember-in-viewport/utils/can-use-dom';
import canUseRAF from 'ember-in-viewport/utils/can-use-raf';
import isInViewport from 'ember-in-viewport/utils/is-in-viewport';

Inside of addons/mixins/in-viewport.js, we’ll import the modules that the mixin requires. The canUseDOM and canUseRAF modules are simple utility files that help us determine whether or not a DOM is available (this is particularly important for running PhantomJS tests and FastBoot/server side rendering) and whether or not the user’s browser supports the requestAnimationFrame API.

To generate a new utility file:

$ ember g util can-use-dom

Again, we don’t want these files inside our users’ app trees, so we’ll delete the folders generated inside of /app.

Updating the Is In Viewport logic

The method for calculating whether or not a DOM element is in the viewport remains mostly unchanged, except with the addition of a new ‘tolerance’ argument.

import Ember from 'ember';

const { merge } = Ember;

const defaultTolerance = {
  top    : 0,
  left   : 0,
  bottom : 0,
  right  : 0
};

export default function isInViewport(boundingClientRect={}, height=0, width=0, tolerance=defaultTolerance) {
  const { top, left, bottom, right } = boundingClientRect;
  const tolerances = merge(defaultTolerance, tolerance);
  let {
    top    : topTolerance,
    left   : leftTolerance,
    bottom : bottomTolerance,
    right  : rightTolerance
  } = tolerances;

  return (
    (top + topTolerance)       >= 0 &&
    (left + leftTolerance)     >= 0 &&
    (bottom - bottomTolerance) <= height &&
    (right - rightTolerance)   <= width
  );
}

With the addition of the tolerance option, addon users can relax how precise the check is. When set to 0, the Mixin only considers an element inside the viewport when it is completely visible inside of the viewport.

Setting up the Class variables

const {
  get,
  set,
  setProperties,
  computed,
  run,
  on,
  $,
} = Ember;

const {
  scheduleOnce,
  debounce,
  bind,
  next
} = run;

const { not }     = computed;
const { forEach } = Ember.EnumerableUtils;

const listeners = [
  { context: window,   event: 'scroll.scrollable' },
  { context: window,   event: 'resize.resizable' },
  { context: document, event: 'touchmove.scrollable' }
];

let rAFIDS = {};

If you haven’t had the chance to use ES2015 features, now’s a good time to learn, since ember-cli-babel has been shipped with ember-cli by default for a while now. Here, we’re destructuring certain methods from Ember, as well as setting up an array of listeners we want to register. I also declare a mutable variable rAFIDS with let — I’ll be using this object to store the ID that’s returned by the requestAnimationFrame function so that we can cancel it later.

Something interesting to note is that these variables are actually shared by all instances of the Mixin. This means if we stored the rAF ID in that variable, it will be overwritten by other instances of the Components that are being watched by the Mixin. So instead, we’ll store each rAF ID as a key (the element ID for the Component) inside of an object. More on that later.

Initial state

_setInitialState: on('init', function() {
  setProperties(this, {
    $viewportCachedEl   : undefined,
    viewportUseRAF      : canUseRAF(),
    viewportEntered     : false,
    viewportSpy         : false,
    viewportRefreshRate : 100,
    viewportTolerance   : {
      top    : 0,
      left   : 0,
      bottom : 0,
      right  : 0
    },
  });
}),

We’ll need to setup some initial values for our Mixin’s state. We do this when the Object the Mixin is mixed into is instantiated, by setting some properties on init. This is because Mixins extend a constructor’s prototype, so certain properties will be shared amongst objects that implement the Mixin — and in our case, we want these to be unique to each instance.

Here, we’re also going to make use of our utility function canUseRAF to let the Mixin know whether to use requestAnimationFrame or fallback to the Ember run loop.

Read only computed properties

For convenience, we’ll add a ‘viewportExited’ computed property (c.f. ‘viewportEntered’) that our addon users can use. Setting this up is simple:

viewportExited: not('viewportEntered').readOnly(),

We’ll also make this computed property read only, because it doesn’t make sense for the addon user to set this manually.

Setting up the DOM element rendered by the component

When the DOM element is inserted into the DOM, we’ll need to setup a few things:

The initial check on render to see if the element is immediately in view
Setting up an observer if we’re not spying on the element
Calling the recursive requestAnimationFrame method
Setting up and removing event listeners if we are spying on the element

_setupElement: on('didInsertElement', function() {
  if (!canUseDOM) { return; }

  const viewportUseRAF = get(this, 'viewportUseRAF');

  this._setInitialViewport(window);
  this._addObserverIfNotSpying();
  this._setViewportEntered(window);

  if (!viewportUseRAF) {
    forEach(listeners, (listener) => {
      const { context, event } = listener;
      this._bindListeners(context, event);
    });
  }
}),

Checking if the DOM element is immediately in view

After the element has been rendered into the DOM, we want to immediately check if it’s visible. This calls the _setViewportEntered method in the afterRender queue of the Ember run loop.

_setInitialViewport(context=null) {
  Ember.assert('You must pass a valid context to _setInitialViewport', context);

  return scheduleOnce('afterRender', this, () => {
    this._setViewportEntered(context);
  });
},

Unbinding listeners after entering the viewport

It makes sense for certain use cases to actually stop watching the element after it has entered the viewport at least once. For example, in an image lazy loader, we only want to load the image once, after which it makes sense to clean up listeners to reduce the load on the app. We do that with the viewportSpy option.

Here, we programatically add an observer on the viewportEntered prop if viewportSpy has been set to false by our addon user. The observer itself doesn’t do much — it unbinds listeners and then removes itself.

_addObserverIfNotSpying() {
  const viewportSpy = get(this, 'viewportSpy');

  if (!viewportSpy) {
    this.addObserver('viewportEntered', this, this._viewportDidEnter);
  }
},

_viewportDidEnter() {
  const viewportEntered = get(this, 'viewportEntered');
  const viewportSpy     = get(this, 'viewportSpy');

  if (!viewportSpy && viewportEntered) {
    this._unbindListeners();
    this.removeObserver('viewportEntered', this, this._viewportDidEnter);
  }
},

Setting up event listeners

Let’s look at binding our event listeners before we take a look at _setViewportEntered, the main method for the mixin. We’ll be using the array of listeners we declared earlier at the top of the file, and binding the event to the appropriate context (window or document), like so:

_bindListeners(context=null, event=null) {
  Ember.assert('You must pass a valid context to _bindListeners', context);
  Ember.assert('You must pass a valid event to _bindListeners', event);

  const elementId = get(this, 'elementId');

  Ember.warn('No elementId was found on this Object, `viewportSpy` will' +
    'not work as expected', elementId);

  $(context).on(`${event}#${elementId}`, () => {
    this._scrollHandler(context);
  });
},

Note that we can actually pass the Component’s elementId (the id attribute that is rendered into the DOM) to the event, which will allow us to only unbind the listener for that particular element. If we didn’t do this, all listeners would have been unbound when the first DOM element enters the viewport, which isn’t what we’d expect.

Handling the event

Now, we can handle the event by debouncing the main method with the viewportRefreshRate set by the addon user. I talk about this in my previous post, so please have a read if you’re not sure how debouncing works with the Ember run loop.

_scrollHandler(context=null) {
  Ember.assert('You must pass a valid context to _scrollHandler', context);

  const viewportRefreshRate = get(this, 'viewportRefreshRate');

  debounce(this, function() {
    this._setViewportEntered(context);
  }, viewportRefreshRate);
},

Unbinding listeners

When we eventually destroy the Component, we want to make sure we also cleanup after ourselves. We’ll have to remove both event listeners and the recursive requestAnimationFrame call:

_unbindListeners() {
  const elementId      = get(this, 'elementId');
  const viewportUseRAF = get(this, 'viewportUseRAF');

  Ember.warn('No elementId was found on this Object, `viewportSpy` will' +
    'not work as expected', elementId);

  if (viewportUseRAF) {
    next(this, () => {
      window.cancelAnimationFrame(rAFIDS[elementId]);
      rAFIDS[elementId] = null;
    });
  }

  forEach(listeners, (listener) => {
    const { context, event } = listener;
    $(context).off(`${event}#${elementId}`);
  });
}

_teardown: on('willDestroyElement', function() {
  this._unbindListeners();
}),

If you recall, the requestAnimationFrame function returns an ID that uniquely identifies the entry in the callback list. We can pass this on to cancelAnimationFrame in order to cancel the infinitely recursive call to the main method. Because we register the Component’s DOM elementId as a key in the rAFIDS object, we can remove the specific rAF call for that single Component. I’ve wrapped the cAF call in an Ember.run.next to avoid a race condition preventing proper cancellation of the rAF recursion that happens occasionally.

Updating the viewportEntered property

Let’s take a look at the main method responsible for setting the ‘viewportEntered’ property. This method does two main things:

Set viewportEntered to true or false
Fire off the next requestAnimationFrame step

_setViewportEntered(context=null) {
  Ember.assert('You must pass a valid context to _setViewportEntered', context);

  const $viewportCachedEl = get(this, '$viewportCachedEl');
  const viewportUseRAF    = get(this, 'viewportUseRAF');
  const elementId         = get(this, 'elementId');
  const tolerance         = get(this, 'viewportTolerance');
  const height            = $(context) ? $(context).height() : 0;
  const width             = $(context) ? $(context).width()  : 0;

  let boundingClientRect;

  if ($viewportCachedEl) {
    boundingClientRect = $viewportCachedEl[0].getBoundingClientRect();
  } else {
    boundingClientRect = set(this, '$viewportCachedEl', this.$())[0].getBoundingClientRect();
  }

  const viewportEntered = isInViewport(boundingClientRect, height, width, tolerance);

  set(this, 'viewportEntered', viewportEntered);

  if ($viewportCachedEl && viewportUseRAF) {
    rAFIDS[elementId] = window.requestAnimationFrame(
      bind(this, this._setViewportEntered, context)
    );
  }
},

As a simple optimization, we can cache the selected DOM element inside the Object as $viewportCachedEl so we don’t have call the expensive DOM node selector method every time. Then, we pass the Component’s element properties to the utility we defined earlier, and set the viewportEntered property to true or false.

If requestAnimationFrame is enabled, we call the method again inside of the rAF method, after binding it to the correct context. Like Function.prototype.bind(), this creates a new function, that when called, has its this keyword set to the correct value (along with any arguments). With that first call after the element is inserted into the DOM, this fires off an infinitely recursive loop that will only end when we cancel it.

Hence, we don’t have to setup event listeners when rAF is enabled. And that’s it for the Mixin!

Recap

Basically, the Mixin does one of two things when implemented by a Component or View:

If rAF is enabled, it sets off an infinitely recursive call to the main method at close to 60FPS (or whatever the user’s monitor refresh rate is), without the use of event listeners. This is then canceled when the Component is destroyed, or if the viewportSpy option has been set to false and the Component has already entered the viewport once.
If not, the Mixin sets up event listeners on the Component’s unique DOM element, and fires the main method whenever the user triggers one of three events (scroll, resize, and touch). Again, the event listeners are removed on destroy and if the viewportSpy option is false.

Unleashing your addon on the Ember community

Now that we’re done with the main addon logic, and writing tests (a topic for another post!), we’re ready to release our addon to the world! I typically use git flow to manage my repos, and it also helps with the release process using git flow release.

At this point, I make sure my readme is written comprehensively to detail how an addon user can use the addon, as well as bump version numbers according to SemVer. GitHub also has a nice way to keep track of your addon’s different named releases, which I tend to use quite often as a way to keep addon users updated about what’s changed in each version.

Once your changes have been merged back into master, you can publish your addon up onto npm:

$ npm publish

Congrats! You’ve written your first addon☺Now you can obsess over your addon’s score at Ember Observer.

Thanks for reading!

This has been a pretty long post, I hope you’ve learned something. If you’d like to ask any questions, please feel free to send me a tweet.

Some of you might probably know that I’ve recently joined DockYard. If you’re looking for Ember experts to augment your staff, work on a greenfield project or an existing one, please get in touch!

Until next time,

Lauren

The Importance of Being Experience First

Fri, 10 Apr 2015 18:17:53 GMT

We’re in the middle of a digital renaissance that has software eating the world. Like the industrial revolution, the digital revolution might see us eventually becoming obsolete, but that’s okay because that’s what progress looks like. To stay relevant, we need to place the Experience First.

Architecting the digital world

The modern architect has her roots in ancient and medieval history. They originated as artisans; master craftsmen such as stone masons and carpenters. In ancient times, there was no clear separation between the role of the architect and the engineer — they were seen as one and the same.

In some ways, the architects of the digital world are similar to those of the physical. There are many parallels between the two, although it’s important to be aware of leaky abstractions, and that they are only similar, not exactly the same.

The craftsmens’ renaissance

We’re currently living in an age of digital renaissance. Software is eating the world, and some of us believe that we’re right in the middle of a great technological revolution — the software revolution.

It’s no longer enough to build a good product or service. The world demands excellence, because good is the new average.

I believe it’s partly a symptom of how efficient manufacturing has become, that we’re experiencing wide scale commoditization of goods and services that were historically considered luxuries. Because of this, we’re also at the start of a new renaissance — one in which there is a resurgence of an appreciation for well designed experiences.

In my EmberConf talk, I defined design to mean more than aesthetics; design is how things work, and encompasses the entire experience across different mediums. Airbnb calls this being Experience First, as opposed to Design First, which suggests that anyone who isn’t a designer has their contributions take a backseat.

“That experience is essentially a story, a narrative which ultimately enjoins us to a brand.” — Om Malik, Gigaom

In other words, it’s obvious that we place value on things that fulfill both form and function. The popularity of beautiful user experiences, both online and offline, are the expression of a digital renaissance that is only going to continue growing.

The rise of website builders and what it means for us

Unlike classical portrait painters, bowling alley pinsetters and other jobs that have become redundant, the digital creator seems to be relatively safe.

With the rise of website builders like Wix, Squarespace, The Grid and portfolio/shop builders like Shopify, BigCommerce and Virb though, it’s easier than ever for an individual or business to get a beautiful looking website created at a fraction of the cost.

The beauty of the web is that once an asset has been made, it effectively costs nothing to clone. A designer with a copy of Sketch or Photoshop can very quickly design a ‘theme’, have it converted into HTML/CSS by a “PSD to HTML” service (as they’re commonly known), and then sell it on one of these site builders. You could very easily get a beautiful looking website setup and live on the web on Squarespace for less than $10 a month.

Why you need to place the Experience First

One thing I’ve learned from my time in Business School, is that humans suck at predicting things. Maybe we’re all going to be made redundant, but the ones that design the best experiences will continue to be more relevant than ever.

If creating a website or app is commoditized, so be it. After all, who’s going to design and build the website builder? The fact is, designing a beautiful experience across different mediums will never be automated, not until we have the technology to build incredibly intelligent Sentient AIs. But by then, we’d all be in trouble, so I wouldn’t worry about it just yet.

Because it’s easier than ever to build a website or app, the experience matters more than ever as the way to differentiate your product or service from the average. When you look to hire a developer or consultancy today, I think it’s important that you seek out the ones that have honed the balance between design and engineering, and have spent time thinking about designing truly delightful online (and offline) experiences.

Joining DockYard

I’ve had a very diverse and varied experience with the web — I went to design school, did a finance degree, and started a company. Recently, I made the exhausting move from halfway across the world in Australia to join DockYard, because we truly care about the entire experience. I’m very proud to be able to call DY my new home.

This post originally appears on Reefpoints — I hope you’ve enjoyed reading!

Special mention to @nfFrenchie, @scottyli and everyone else who helped review this post.

Ember.js & Reactive Programming — Computed Properties and Observers

Fri, 16 Jan 2015 22:08:07 GMT

Reactive Programming (or RP for short) is a programming paradigm that gets thrown around a lot, but its clear that there is much confusion about what it actually is. RP is a general programming paradigm, but is particularly suited to creating reactive user interfaces.

The simplest analogy to understand RP is that of a ‘spreadsheet’ — if you’ve ever dabbled with Excel/Google Spreadsheet formulas, congratulations, you’ve done some reactive programming already!

Ever since the introduction of AJAX, users have grown used to, and expect reactive user interfaces in the web applications that they use. Through the use of the RP paradigm, we can build beautiful user experiences and reactive interfaces in Ember.js — in particular, we’ll look at how we can use computed properties and observers to do just that.

What is Reactive Programming?

Take a look at this screenshot from Google Sheets. It’s the most basic spreadsheet possible: we have two user input cells, A1 and B1 (the letter representing the column, and the number representing the row). Each cell contains a static value (in this case, they’re both 1), that the user has entered.

A simple formula in Google Sheets

In cell C1, we have a dynamic value =A1+B1, which is self-explanatory. The value of C1 is simply the addition of cells A1 + B1, which is 2 in this case. Changing values in either A1 or B1 immediately updates the value of C1, without us needing to imperatively update its value every time one of its dependent cells change.

Reactive programming is about the flow of data and declaratively maintaining the relationships between that data.

If you did this in vanilla JavaScript or jQuery, you’d have to explicitly listen to ‘change’ events on the inputs, and then manually update the value of C1. Not fun! And this is only a simple example — if you were building a complex web app without a more declarative approach, your code quickly becomes difficult to maintain and reason about, and worse, hard to test.

This imperative struggle has given rise to JavaScript frameworks such as Ember, React and Angular, which makes web applications easier to build, maintain and test.

The Observer Pattern

JavaScript is an object oriented language, and features inheritance of properties and methods. Unlike Ruby or Python, which have ‘classical’ inheritance, JavaScript has ‘prototypal’ inheritance.

Ember.Object (which is Ember.CoreObject with the Ember.Observable mixin applied) implements a more classical JavaScript object, and together with the observer pattern (computed properties and observers), allows data to be updated whenever a change is made.

In that sense, the observer pattern provides a mechanism for which RP can happen in Ember.js. Thus, any class that has the Ember.Observable mixin is observable, and you can apply RP techniques to it.

Functional Reactive Programming

Functional Reactive Programming (FRP) is RP’s functional cousin. In functional programming, data should be immutable, and programs stateless. JavaScript isn’t a pure functional language (see Erlang, Haskell, or Clojure for examples), but we can certainly write our programs to be more functional.

In FRP, user interactions are expressed as streams (also called signals), or value over time. The simplest example is one you’re probably already very familiar with — the mouse.

Image from ‘Elm: Concurrent FRP for Functional GUIs’ by Evan Czaplicki

If you imagine your table or mousepad to be a cartesian plane, then the movement of your mouse can be expressed in (x, y) coordinates as Mouse.position. Moving your mouse immediately updates its coordinates, and there is an clear relationship between the physical position of the mouse and its digital representation on your screen.

To do this in JavaScript would require significantly more code compared to an FRP language like Elm (which does it in far fewer lines): you’d have to manually extract the mouse position on every ‘mousemove’ event, and then describe exactly how to update the displayed value.

Every mouse movement is thus a value over time, (imagine an array of events with data) and using functional programming techniques like Array.prototype#map, #filter, #reduce, and #concat (all of which return new arrays or values) we can transform our data in order to make our interfaces reactive.

Libraries like bacon.js make FRP possible in JavaScript. Ember doesn’t ship with as many of bacon.js’s features, but we can make use of a few key tools to make our goal of building reactive user interfaces easier.

Computed properties

The current Ember guides on computed properties

Computed properties are built on top of the observer pattern, and let us take one or more properties and reactively transform or manipulate their data to return some new value. The computed property updates whenever one of their dependent values change, ensuring that relationships are always kept in sync.

You’ve probably seen this example a number of times:

import Ember from 'ember';

var computed = Ember.computed;
var get      = Ember.get;

export default Ember.Object.extend({
  fullName: computed('firstName', 'lastName', function() {
    return get(this, 'firstName') + ' ' + get(this, 'lastName');
  })
});

This is great! We can now use fullName like we would any other property on the object that it sits in.

[Computed properties are] … super handy for taking one or more normal properties and transforming or manipulating their data to create a new value.

With computed properties, we can also avoid needless computation through caching, which prevents re-computation even though the input has not changed.

Computed property macros

As our application grows larger and more complex however, we might find that we have repetition in our computed properties.

In order to make our code DRY and testable, it’s a good idea to think about refactoring some of our shared computed properties into computed property macros. A computed property macro can really be thought of as a function that returns the definition of a computed property (you can return an observer as well). Ember ships with a few handy ones out of the box.

Let’s say we decide that instead of calling the property fullName on our object, we want to use name, for whatever reason. A naïve approach might be to do something like this:

An anti-pattern

import Ember from 'ember';

var computed = Ember.computed;
var get      = Ember.get;

export default Ember.Object.extend({
  fullName: computed('firstName', 'lastName', function() {
    return get(this, 'firstName') + ' ' + get(this, 'lastName');
  }),

  name: computed('fullName', function() {
    return get(this, 'fullName');
  })
});

This might seem superfluous, and it is. Let’s use one of the computed property macros (computed.alias) that Ember ships with instead.

import Ember from 'ember';

var computed = Ember.computed;
var get      = Ember.get;

export default Ember.Object.extend({
  fullName: computed('firstName', 'lastName', function() {
    return get(this, 'firstName') + ' ' + get(this, 'lastName');
  }),

  name: computed.alias('fullName')
});

That’s better! Computed property macros let us re-use common functionality and share them throughout our app, and avoids repeating the logic every time we need it. Because the above use case is so common, the fine folk in charge of Ember.js have included it as a default computed property macro.

Observers

Unlike computed properties, observers don’t return new values. Instead, they only observe changes to properties, and are synchronously invoked whenever the dependent properties change.

For example, let’s say we have an Ember.Object representing a Child.

import Ember         from 'ember';
import notifyParents from 'notify-parents';

var observer = Ember.observer;
var computed = Ember.computed;
var not      = computed.not;
var get      = Ember.get;

export default Ember.Object.extend({
  firstName: 'Lauren',
  lastName:  'Tan',
  isAtHome:  false,

  isOutside: not('isAtHome'),

  fullName: computed('firstName', 'lastName', function() {
    return get(this, 'firstName') + ' ' + get(this, 'lastName');
  }),

  notifyParentsWhenAtHome: observer('isAtHome', function() {
    var userIsAtHome = get(this, 'isAtHome');
    if (userIsAtHome) {
      notifyParents(get(this, 'fullName'), new Date());
    }
  })
});

The Child has properties for her first and last name, and whether or not she is at home. Note the use of Ember.computed.not in the isOutside property, which simply means that whether or not the child is at home is inversely related to whether or not she is outside. With computed properties, this relationship is always maintained, and we can be sure that our interface also updates accordingly when the dependent value changes.

The notifyParentsWhenAtHome observer then observes the property isAtHome, and if that is true, we notify the child’s parents the child’s full name and the exact time she returned home.

A Functional Reactive Example with Ember Data and Promises

As a simple example, let’s imagine we’re building an app that has 3 models: Teams, Players and Coaches. A Team has many players, and one Coach. I assume some familiarity with Promises in this example.

Players and Coaches

These are very simple models and are quite self-explanatory.

import DS from 'ember-data;'

export default DS.Model.extend({
  name:      DS.attr('string'),
  score:     DS.attr('number'),
  team:      DS.belongsTo('team', { async: true }),
  coaches:   DS.hasMany('coach', { async: true })
});

import DS from 'ember-data;'

export default DS.Model.extend({
  name:      DS.attr('string'),
  score:     DS.attr('number'),
  team:      DS.belongsTo('team', { async: true }),
  players:   DS.hasMany('player', { async: true })
});

Teams

import Ember from 'ember';
import DS    from 'ember-data';

var computed = Ember.computed;
var get      = Ember.get;
var RSVP     = Ember.RSVP;

export default DS.Model.extend({
  name:    DS.attr('string'),
  players: DS.hasMany('player', { async: true }),
  coach:   DS.belongsTo('coach', { async: true }),

  coachScore: computed.alias('coach.score'),

  playersScore: computed('players.@each.score', function() {
    var promise = get(this, 'players')
    .then(function(players) {
      return RSVP.all(players.mapBy('score'))
    })
    .then(function(scores) {
      return scores.reduce(function(previous, current) {
        return previous + current;
      }, []);
    });
    return DS.PromiseObject.create({ promise: promise });
  }),

  score: computed('playersScore', 'coachScore', function() {
    var playersScore = get(this, 'playersScore');
    var coachScore   = get(this, 'coachScore');

    return playersScore * coachScore;
  })
});

Let’s say that the Team’s score is made up of the sum of all its Players’ scores, multiplied by the Coach’s score. We first create two computed properties, coachScore and playersScore, which return a single score for the Coach and Player respectively. Because a Team only has one Coach, it’s easy to get the Coach’s Score using a computed alias.

As the Team has many Players, it’s a little bit trickier to calculate the sum of their scores. Unfortunately, we can’t do:

computed.alias('players.score');

Because the players property returns an array of Player models, the array itself does not have the property ‘score’. We actually need to map over each Player’s score, and then add them together. Using functional programming, we can make use of Ember.Array#mapBy to first return a new array of all Player scores.

We then reduce the array down to a single value by adding them all together. To get the Team’s score (score), we just multiply the Coach’s score with the Players’ score.

After defining these 3 computed properties, we’ll have three functional and reactive properties that can be then used in our template. Whenever a player’s or coach’s score changes, the team score updates immediately in the user interface, without us having to imperatively update DOM elements and the like. Awesome!

A Note on Dependent Computed Properties

Because you can have computed properties observe other computed properties, it’s easy to build overly complex data relationships. It’s also possible to create circular dependencies (i.e. infinite loops), so be careful about how deep down the rabbit hole you go.

Building Your Own Computed Property Macros

In another post, I wrote about writing your own computed property macro to do simple text search. I won’t go into the details here, but have a read if you’d like to see how you can write your own macros. If you notice your computed properties being repeated in multiple areas in your app, refactoring them into re-usable macros are a great way to improve the maintainability and testability of your app.

I also recommend looking at ember-cpm by @miguelcamba, which is a collection of more computed macros, available both as an ember-cli addon and for globals based Ember apps.

Why You Should Care

If you’ve ever built an app with complex user interactions without a framework like Ember before, you’ll know how difficult it is to effectively manage the flow of data through the app.

As front end developers, we strive to build delightful and reactive experiences our users. Using modern tools like Ember.js and functional reactive techniques help us write more declaratively, freeing us from the shackles of low level DOM manipulation and jQuery spaghetti.

My 2014 in Review — Or How I Beat Impostor Syndrome

Sun, 28 Dec 2014 11:05:41 GMT

I’ll remember 2014 as the year I was challenged and grew the most — both personally, and professionally as a UI designer and front end developer.

This year, amongst other things, my writing on Ember.js has been read by thousands; I joined the Ember.js documentation strike team; and I was accepted to speak at EmberConf, my first ever talk at a technical conference.

As a bit of context, I’ve been a UI designer for a number of years, but only started becoming more serious about front end development a few years ago. I’m proud of the things I’ve accomplished this year despite my limited experience, and I can’t wait to see what I’ll learn and achieve next year.

I wasn’t always this confident, though. I’ve battled with impostor syndrome for a good part of my adult life, and only recently realised that it’s no longer as big of a problem as it used to be. If you had told me 2 years ago that I would be speaking in front of an audience of hundreds about Ember.js, I would have laughed nervously and then run away crying.

Background courtesy of dribbble.com/Lumberjacks

Know Your Enemy

Until recently, I had never heard of the term ‘impostor syndrome’. I was familiar with the symptoms — of feeling like a fraud, surrounded by people smarter and more capable than you could ever be — but hadn’t realised that it was an actual ‘thing’ you could have. It was a bit of a relief finding out that I wasn’t the only one suffering from what I had originally attributed to a lack of intellect. It also became apparent that the issue wasn’t so much that I wasn’t intelligent, but rather that I both lacked confidence and had copious amounts of insecurity.

Shortly after graduating with a degree in Finance, my friend Scott and I started working on a startup idea. At the time, both of us had very little technical skills, and unfortunately, ran out of money before we could turn it into a viable business. We had both realised that it would probably be a good idea to learn more technical skills before working on another startup, so we both took a few months off to reflect.

I had no idea what I was doing with my life.

When I first started learning Ruby on Rails and JavaScript, I was in over my head. Up till then, my only introduction to programming was a Financial Modelling course I did in university using VBA in Excel. Sure, I learnt about the basic building blocks of programming, such as variables, loops, conditionals and types, but it was all on a very shallow basis. And even though I knew the basics, I still couldn’t fathom how they worked together to become an actual web application.

I felt horribly out of place in the rapidly moving world of web development, and it was crippling. I had no confidence, and many times I thought I would just give up on my dreams to join the corporate rat race.

What Am I Good At, Really?

I’ve been designing UIs and graphics since I was 15, when I ‘stumbled upon’ a copy of Macromedia Fireworks, and then later Adobe Photoshop. When we were still in high school, my friend introduced me to this cool thing called HTML that was “a way of making websites”, and he did that by showing me how to use the marquee tag. That’s right, my first line of HTML was:

<marquee>Hello world</marquee>

From there, I discovered other aspects of basic HTML and CSS, and eventually, the wonderful world of slicing my Photoshop designs into tables. I was hooked on the idea that I, a nobody, could create and publish these websites to a potentially unlimited audience.

With all my time spent tinkering around with HTML/CSS, FTP and graphic design (the Good Old Days™), my grades in high school suffered, and I barely made it into design school. I remember thinking at the time that all this web stuff was pretty neat, but I couldn’t imagine it being an actual career option, so I didn’t take any web development courses in school; instead focusing on game design and illustration for concept art. In hindsight, I’m pretty glad I took that path, as the skills I learnt — drawing, painting, anatomy, perspective, colour, lighting— have been very complementary to my professional life.

I wasn’t aware of it back then, but if I immerse myself in something, I get good at it very quickly. I’m someone who learns best by trying, failing, and doing it all over again.

I finished design school, but I still didn’t think web development would ever be a viable career. I loved drawing and painting, but I didn’t think I would enjoy it as a job, and jobs in concept art were scarce if you lived in Singapore.

Faced with the prospects of unemployment and not knowing what I wanted to do in life, I decided to do something more ‘realistic’. For the next few years I sat myself down and brushed up on the math I flunked through in high school to complete my Finance degree in Australia. This was my first brush with impostor syndrome — I was in a foreign country, surrounded by people who were smarter than me, and I had no idea what I had got myself into. Throughout my first semester, I kept believing I wasn’t smart enough to go from design to finance, so I worked very hard and studied continuously — I didn’t have much of a social life.

By the end of my first semester, even after I had finished near the top of my class, I still didn’t think I had it in me. The constant fear of being found out that I wasn’t good enough actually spurred me on to work harder; and what I lacked in intelligence, I decided I would make up for with sheer determination and grit.

When I finally finished my degree, I graduated in the Dean’s list and still didn’t think I knew anything about finance. In my mind, I was the world’s biggest impostor.

Can I Really Do This?

After my first startup failed and months spent learning front end development, Scott got in touch with me again. He had hacked together a little Rails app for visualising price data on eBay that had received a lot of attention on Hacker News. He called it ‘marketprice’, and he thought I would be a great addition to the team. I didn’t tell him then, but I thought he was crazy to want to work with me again.

I spent 2013 working hard on ThePriceGeek (our new name), building it mostly with jQuery spaghetti and Sass. I learnt a lot, but I still felt like a wannabe front end developer. We were in the Melbourne Accelerator Program, and featured on CNN Money, Lifehacker, the IBTimes, and various other internet media. Although we achieved some success with ThePriceGeek, it was a highly competitive landscape, and after a year of working on it with limited traction, we made the difficult decision to stop. At its peak, we only made about a thousand dollars in monthly affiliate revenues, which wasn’t enough to sustain itself.

In late 2013, my good friend Joe Valente asked if I was interested in working at a pre-product startup to do more front end development. Impostor syndrome struck again, so I put on a brave face and went for the interview, thinking I would give it a go even if I wasn’t very good.

Every time I start something new, my confidence takes a hit and impostor syndrome strikes — “I don’t think I can do this.”

I ended up being hired to work with Dan Groch and Wade Keenan, two of the sharpest business minds I’ve had the pleasure to work with, and Chris Atkins, a gifted polyglot programmer who I still look up to. After we thrashed out what exactly it was we were building, we settled on Rails, postgres and Ember.js as a technology stack. I had never worked with Ember.js, let alone a client side MVC framework before, so you can imagine how terrified I was.

After months of struggling through Ember’s documentation, we finally managed to build a prototype that the founders successfully raised seed funding with. I spent the rest of the year skilling up significantly on JavaScript, Ember.js, and testing. In September this year, I began writing about the lessons I learnt in Ember.js as a way of recording my thoughts, and never imagined that anyone would want to read them.

My very first article was about how I figured out how to implement a drag and drop interface in Ember.js with HTML5 and minimal JavaScript, and I submitted it to /r/emberjs on a whim. It turns out that Tom Dale frequents that subreddit, and tweeted about my post. I was happy — maybe I’m not so bad after all?

I made a decision then, to continue writing about interesting things I was doing in Ember.js, and I would beat impostor syndrome by doing interesting things and then telling people about it. Admitting you have impostor syndrome is an important first step towards beating it.

Do Things, Tell People —The Real World REPL

Since that post, I’ve written a few more that have been pretty well received. Tom and Leah reached out to me on Twitter to encourage me to apply to speak at EmberConf, and I’m glad I did, because I just learnt a few days ago that my talk was accepted (yay!).

I love opening up a blank JSBin and just hacking together an idea to see if it works — most recently, I built an Ember.js component and injected service to lazy load embedded videos completely in JSBin. It became my most retweeted blog post, and Yehuda Katz even said it was cool (cue fangirl moment). I was really happy, and I finally realised that I had figured out a way to overcome impostor syndrome.

Achievement unlocked!

Grit

I now know for a fact, that every time I start something new and unfamiliar, impostor syndrome inevitably rears its ugly head.

I started working at Homely in the start of December, tasked with refactoring a jQuery monolith into something more maintainable and testable (there were no JavaScript tests, even though the JavaScript was powering the entire front end). Faced with working with an unfamiliar technology stack (.NET, React.js) and a massive refactor ahead of me with no tests, I felt really nervous and scared in my first week.

I’m not the smartest, or most talented.

If there’s one thing I’m good at though, it’s being stubborn and bashing my head against things until I figure out how it works. That grit, combined with an ability to learn things quickly, have made the struggle with impostor syndrome so much easier. Thankfully, I feel more confident now, and have led the Homely team in redesigning a large feature in React.js, complete with unit and integration tests.

Do Things, Tell People, Learn

I’ve come a long way since I first started learning HTML/CSS in high school, and I’ve finally discovered what I want to do with my life. I’m not an expert by any means, but I know that whatever knowledge I lack, I can quickly learn. If you’re familiar with the Lean Startup, you’ll realise that I’ve adapted “Build, Measure, Learn” into a method that works for me. I’ll know I’ll never stop feeling like an impostor, but at least I now have a method to beat it.

“First do it, then do it right, then do it better.” — Addy Osmani

As you can probably imagine, I don’t feel prepared (or qualified) at all to speak at EmberConf, so I’ll be shutting myself in, spending the next few months preparing intensely for my talk — which by the way, is about ‘Ambitious UX for Ambitious Apps’ — and I know that I’ll be over-prepared by the time the conference begins. I wouldn’t have it any other way.

If you’ve ever faced impostor syndrome in your life, I’d love to hear about it, especially if you’re a woman and/or minority working in technology. I don’t know if my methods will work for everyone (if anyone at all), but I hope my writing spurs you on to discover a method of your own.

Happy new year!

Lauren ❤

Submit an Ember TextArea with Command or Ctrl + Enter

Mon, 22 Dec 2014 12:17:33 GMT

It’s Christmas in a few days, so I only have time for a short post this week.

You might have an Ember TextArea in your app somewhere, perhaps as a comment form or some other input, for submitting multi-line strings (e.g. formatted with Markdown) to some API. If you’ve ever commented on a Github issue or pull request, you’ll notice that the form doesn’t submit if you hit enter while it’s in focus. Instead, it only submits when you hit ctrl or ⌘ + enter.

In this post, we’ll explore the few lines of code we need to extend the default Ember TextArea to do just that.

JS Bin Demo

Reopening Ember.TextArea

Ember makes it really easy to reopen classes so that we can add new methods and properties, or modify existing ones. It’s analogous to adding methods to some prototype instead of adding them to each and every instance of that class. Generally speaking, reopenClass adds methods to the class itself, while reopen adds methods to instances of that class.

‘reopen’ is used to add instance methods and properties that are shared across all instances of a class.

For example, if you wanted your Ember app to use the browser’s history API instead of a hashchange event, you would have to reopen the Router, and set it’s location key/value to ‘history’:

App.Router.reopen({
  location: 'history'
});

In our case, we’re reopening Ember.Textarea, and modifying the default event keyDown to check if the event has the right keycode and modifier key (_isValidCombination). If it is, the TextArea (which extends Ember.Component — it’s just a special kind of component) sends an action we named modifiedSubmit. Then in our template, we just need to bind that action name to some controller action to handle it and we’re done!

{{textarea modifiedSubmit="someControllerAction" value=someText}}

export default Ember.TextArea.reopen({
  keyDown: function(event) {
    if (this._isValidCombination(event)) {
      this.sendAction('modifiedSubmit');
    }
  },
  _hasCorrectModifier: function(event) {
    return event.ctrlKey || event.metaKey;
  },
  _isCorrectKeyCode: function(keyCode) {
    return keyCode === 13;
  },
  _isValidCombination: function(event) {
    return this._hasCorrectModifier(event) && this._isCorrectKeyCode(event.keyCode);
  }
});

Reopening and Extending Other Classes to Keep Things DRY

As you can see, it’s really easy to reopen and add or overwrite existing methods on Ember classes. It’s a powerful concept that can also be easily abused, so have a read of the Ember guides about the Ember object model to get a sense of how it all works. Many classes in Ember inherit from Ember.Object as a base, so knowing about the object model will be useful in getting a better understanding of how Ember works.

Ember.Object#extend

This method extends a sub-class from some Ember Object. For example, you might have noticed that all your controllers extend Ember.Controller/ObjectController/ArrayController:

export default Ember.Controller.extend({ ... });

That means we can also create our own controllers and other objects that can then be used as a new base class:

base.js

export default Ember.Controller.extend({
  someComputed: Ember.computed('foo', 'bar', function() {
    return get(this, 'foo') + ' ' + get(this, 'bar');
  })
});

Then:

other.js

import BaseController from 'base';

export default BaseController.extend({
  ... // some other classes that need the 'someComputed' property
});

Now all classes that extend from ‘BaseController’ will automatically inherit the someComputed computed property, and you don’t have to define it a million times, keeping your code DRY. You can extend pretty much anything: computed properties, actions, and even lifecycle hooks.

This doesn’t just apply to controllers — you can do the same for models, components, views, routes… Basically anything that extends Ember.Object.

Merry Christmas and Thanks for Reading!

I hope you’ve enjoyed reading this little blog post!

What I’ve been up to

Over the next few weeks and months, I’ll be working on improving the Ember Getting Started Guide (GSG) alongside the Ember documentation strike team. We’re aware that Ember’s documentation isn’t as strong as we’d like, so we’ll be taking this opportunity to redesign and rewrite it from the ground up to ensure Ember’s on-boarding story for new developers is best in class in the run up to 2.0.

If you have any suggestions, ideas or feedback for the new GSG, please tweet me! Anything, no matter how small or insignificant, will be helpful. If you like my writing, I hope I’ll be able to inject a little bit of _potetotes goodness into the GSG, and if you don’t, please let me know ☺

See you in the new year! — Lauren

Lazy Loading Videos in Ember

Sun, 14 Dec 2014 10:28:26 GMT

If you’re like me, every time you embed a video iframe into your app you feel a little dirty. Embedding an iframe means loading an entire html document and the crazy amounts of resources it brings along with it. What’s worse is having to embed multiple videos — you really start to feel the performance hit the more videos you add.

Lazy loading is a design pattern for deferring initialization of objects until we actually need them (as opposed to eager loading). In our case, we’d like to use lazy loading to display a thumbnail of the video as a placeholder, and only render the iframe when the user requests it (probably by clicking on it). Lazy loading resource heavy video embeds helps improve render performance of our app, and the best part is that it does not negatively affect the user experience.

In this post, we’ll build a simple component and service to handle lazy loading of Youtube and Vimeo videos. I’d like the component’s API to look something like this:

{{lazy-video provider="youtube" videoId="gvdf5n-zI14"}}
{{lazy-video provider="vimeo"   videoId="51771300"}}

JS Bin Demo

Retrieving the Right URLs

The Lazy Video service is basically our interface to use different providers. It needs a bit of refactoring, but you can see that it doesn’t do that much except serialize URLs. Eventually we’ll be able to add our own providers pretty easily.

import Ember from 'ember';
import youtube from 'ember-lazy-video/lazy-video-providers/youtube';
import vimeo from 'ember-lazy-video/lazy-video-providers/vimeo';

export default Ember.Object.extend({
  getUrl: function(provider, endpoint, videoId, opts) {
    var params;
    opts = (typeof opts === "undefined") ? {} : opts;
    params = Ember.$.param(opts);
    return this.get(provider)[endpoint](videoId) + '?' + params;
  },
  youtube: youtube,
  vimeo: vimeo
});

For now, let’s add Youtube and Vimeo providers:

import Ember from 'ember';

export default {
  apiUrl: function(videoId) {
    return '//gdata.youtube.com/feeds/api/videos/' + videoId;
  },
  embedUrl: function(videoId) {
    return '//www.youtube.com/embed/' + videoId;
  },
  thumbnailUrl: function(videoId) {
    return Ember.RSVP.resolve('//img.youtube.com/vi/' + videoId + '/maxresdefault.jpg');
  }
};

import Ember from 'ember';

export default {
  apiUrl: function(videoId) {
    return '//vimeo.com/api/oembed.json?url=http%3A//vimeo.com/' + videoId;
  },
  embedUrl: function(videoId) {
    return '//player.vimeo.com/video/' + videoId;
  },
  thumbnailUrl: function(videoId) {
    var apiUrl = this.apiUrl(videoId);
    return new Ember.RSVP.Promise(function(resolve) {
      Ember.$.getJSON(apiUrl).then(function(res) {
        resolve(res.thumbnail_url);
      });
    });
  }
};

These providers don’t do anything too complicated. Youtube’s thumbnails are predictably named, so we can just return strings with the correct videoId. Unfortunately Vimeo’s thumbnail URL isn’t as simple, but it’s nothing simple AJAX can’t handle. If you haven’t dealt with Ember promises much before, we’re just wrapping a jQuery AJAX call inside of an RSVP promise, and resolving the promise with the thumbnail URL from the API response.

Injecting the Service into our Component

import LazyVideoProviders from 'ember-lazy-video/services/lazy-video-providers';

export default {
  name: 'lazy-video',
  initialize: function(container, application){
    application.register('service:lazy-video-providers', LazyVideoProviders, { singleton: true });
    application.inject('component:lazy-video', 'providers', 'service:lazy-video-providers');
  }
};

With that all done, we can inject the Lazy Video providers service into our single component, and call it ‘providers’. This means we can simply call the service from within our component with:

this.get('providers'); // 'this' being the component

The Lazy Video Component

The component works by first asking the service for the right embed and thumbnail URLs. It then sets an inline style for the background to be the video’s thumbnail. Because the iframe embed is disabled by default, the component renders the thumbnail until the user clicks on it, at which point it renders the iframe with the correct embed URL.

I stole the SVG for Youtube’s play button as a default overlay on top of the thumbnails, to let our users know that this is a video. Sorry Youtube! If we specify a block in our component though, the overlay won’t appear and we can design our own play button. This is done with transclusion and the ability to check if a template was passed into the component’s block:

{{#if template}}
  {{yield}}
{{else}}
  <p>Do something else</p>

{{#if isDisplayed}}
  <iframe {{bind-attr src=videoSrc}} width="100%" height="100%" frameBorder="0" allowFullScreen></iframe>
{{else}}
  {{#if template}}
    {{yield}}
  {{else}}
    <div class="lazyLoad-play">
      <svg>
        <path fill-rule="evenodd" clip-rule="evenodd" d="M84.15,26.4v6.35c0,2.833-0.15,5.967-0.45,9.4c-0.133,1.7-0.267,3.117-0.4,4.25l-0.15,0.95c-0.167,0.767-0.367,1.517-0.6,2.25c-0.667,2.367-1.533,4.083-2.6,5.15c-1.367,1.4-2.967,2.383-4.8,2.95c-0.633,0.2-1.316,0.333-2.05,0.4c-0.767,0.1-1.3,0.167-1.6,0.2c-4.9,0.367-11.283,0.617-19.15,0.75c-2.434,0.034-4.883,0.067-7.35,0.1h-2.95C38.417,59.117,34.5,59.067,30.3,59c-8.433-0.167-14.05-0.383-16.85-0.65c-0.067-0.033-0.667-0.117-1.8-0.25c-0.9-0.133-1.683-0.283-2.35-0.45c-2.066-0.533-3.783-1.5-5.15-2.9c-1.033-1.067-1.9-2.783-2.6-5.15C1.317,48.867,1.133,48.117,1,47.35L0.8,46.4c-0.133-1.133-0.267-2.55-0.4-4.25C0.133,38.717,0,35.583,0,32.75V26.4c0-2.833,0.133-5.95,0.4-9.35l0.4-4.25c0.167-0.966,0.417-2.05,0.75-3.25c0.7-2.333,1.567-4.033,2.6-5.1c1.367-1.434,2.967-2.434,4.8-3c0.633-0.167,1.333-0.3,2.1-0.4c0.4-0.066,0.917-0.133,1.55-0.2c4.9-0.333,11.283-0.567,19.15-0.7C35.65,0.05,39.083,0,42.05,0L45,0.05c2.467,0,4.933,0.034,7.4,0.1c7.833,0.133,14.2,0.367,19.1,0.7c0.3,0.033,0.833,0.1,1.6,0.2c0.733,0.1,1.417,0.233,2.05,0.4c1.833,0.566,3.434,1.566,4.8,3c1.066,1.066,1.933,2.767,2.6,5.1c0.367,1.2,0.617,2.284,0.75,3.25l0.4,4.25C84,20.45,84.15,23.567,84.15,26.4z M33.3,41.4L56,29.6L33.3,17.75V41.4z"></path>
        <polygon fill-rule="evenodd" clip-rule="evenodd" fill="#FFFFFF" points="33.3,41.4 33.3,17.75 56,29.6"></polygon>
      </svg>
    </div>
  {{/if}}
{{/if}}

import Ember from 'ember';

export default Ember.Component.extend({
  provider          : null,
  isDisplayed       : false,
  videoTitle        : null,
  videoId           : null,
  classNames        : [ 'lazyLoad-container' ],
  attributeBindings : [ 'style' ],
  videoThumbnail    : null,

  click: function() {
    this.set('isDisplayed', true);
  },

  videoSrc: Ember.computed('provider', 'videoId', function() {
    var providers = this.get('providers');
    var provider  = this.get('provider');
    var videoId   = this.get('videoId');
    return providers.getUrl(provider, 'embedUrl', videoId, { autoplay: 1 });
  }),

  _getVideoThumbnail: (function() {
    var providers = this.get('providers');
    var provider  = this.get('provider');
    var videoId   = this.get('videoId');
    providers.get(provider).thumbnailUrl(videoId).then(function(res) {
      this.set('videoThumbnail', res);
    }.bind(this));
  }).on('didInsertElement'),

  style: Ember.computed('videoThumbnail', function() {
    var thumbnail = this.get('videoThumbnail');
    return 'background-image: url(' + thumbnail + ') center center no-repeat';
  })
});

.lazyLoad-container {
  cursor: pointer;
  width: 100%;
  height: 100%;
  background: black;
  background-size: cover;
  background-position: center center;
  background-repeat: no-repeat;
  &:hover {
    .lazyLoad-play SVG {
      fill: rgb(206, 19, 18);
    }
  }
}

.lazyLoad-play {
  $width: 85px;
  $height: 60px;
  $marginLeft: $width / -2;
  $marginTop: $height / -2;
  width: $width;
  height: $height;
  margin-left: $marginLeft;
  margin-top: $marginTop;
  cursor: pointer;
  outline: 0;
  position: absolute;
  top: 50%;
  left: 50%;
  z-index: 1000;
  svg {
    height: 100%;
    width: 100%;
    fill: rgb(31,31,31);
    @include opacity(0.9);
    cursor: pointer;
  }
}

With a little bit of CSS to make the play button a little snazzier, we’re done with our dead simple component!

Where to go from here

I originally started writing this code inside of an Ember.js flavoured JSBin. It’s a great playground to experiment and tinker with ideas before you decide you want to commit to writing something in greater detail.

As you can probably tell, we could refactor the code we’ve written into something more reusable and extendable. For example, we could rewrite it in a way so that adding new providers is easy, and for the ability to customize the kind of event that triggers the display of the embed. We could even abstract it more so that the component lazy loads anything, and not just videos. After experimenting with our idea in the JS Bin and getting a sense of what we want to build, we should also start writing the right tests to confidently be sure that our code does what we intend it to.

First do it, then do it right, then do it better — Addy Osmani

As always, it’s been a pleasure writing and I hope you’ve enjoyed reading. I’ll be working on making this into a reusable Ember addon over the next week or so in my spare time, I invite you to contribute if you’d like to.

In the next week or two, I’ll be writing about the process for turning a little idea in a JS Bin into a proper well tested Ember addon. Follow me on twitter if you’d like to read more of my ramblings!

Adding Flash Messages to an Ember App

Sun, 30 Nov 2014 06:40:17 GMT

One of Jakob Nielsen’s 10 heuristics for user interface design is Visibility of System Status, or in other words, keeping users informed about the status of the system through appropriate and timely feedback. A mechanic for fulfilling this heuristic is the use of flash messages, which are concise notifications that appear briefly in the user interface before being dismissed automatically (or manually).

In this post, we’ll learn about creating a service that can be injected into Ember Controllers and Routes, that lets us easily add a flash message to our app. We can then trigger these messages in specific actions with a simple API. Let’s get to it!

The flash message addon in action

Planning our Approach

On a high level, we’ll be creating a singleton FlashMessageService that injects itself into all Ember Controllers and Routes. The service will contain a queue of messages that dequeue automatically after a certain amount of time has elapsed.

These messages can then be created from any Ember Controller or Route, then rendered in the application template.

Update (1st Feb 2015)

I’ve also made this an ember-addon — you can install it with:

$ ember install:addon ember-cli-flash

or:

$ npm install --save ember-cli-flash

JS Bin Demo

The Flash Message Service

View full gist

The Flash Message Service is an Ember.Object that holds a queue of Flash Messages. The public API will allow us to create success, info, warning and danger type messages, as well as add flash messages with custom type, and clear all visible flash messages.

Usage is very simple. From within a Controller or Route:

actions: {
  successAction() {
    Ember.get(this, 'flashes').success('Success!', 2000);
  },

  warningAction() {
    Ember.get(this, 'flashes').warning('This is a warning message'); // timeout is optional
  },

  infoAction() {
    Ember.get(this, 'flashes').info('You just did something...', 500);
  },

  dangerAction() {
    Ember.get(this, 'flashes').danger('So danger');
  },

  customAction() {
    Ember.get(this, 'flashes').addMessage('This is a flash with a custom type', 'myCustomType', 3000)
  },

  clearMessages() {
    Ember.get(this, 'flashes').clear(); // clears all visible flash messages
  }
}

Props

queue          : Ember.A([]),
isEmpty        : computed.equal('queue.length', 0),
defaultTimeout : 2000,

The Flash Service starts out with an empty array as its queue property. Flash messages that are created are pushed into this queue, and removed when their timeouts have elapsed. We also setup a global defaultTimeout, in case one isn’t specified when creating new flash messages.

Public methods

  success(message, timeout=get(this, 'defaultTimeout')) {
    this._addToQueue(message, 'success', timeout);
  },

  info(message, timeout=get(this, 'defaultTimeout')) {
    this._addToQueue(message, 'info', timeout);
  },

  warning(message, timeout=get(this, 'defaultTimeout')) {
    this._addToQueue(message, 'warning', timeout);
  },

  danger(message, timeout=get(this, 'defaultTimeout')) {
    this._addToQueue(message, 'danger', timeout);
  },

The success, info, warning, and danger methods simply curry the _addToQueue method with their types filled in as you’d expect. Also note the use of es6 syntax here — we can pass in default values for timeout. Awesome!

  addMessage(message, type='info', timeout=get(this, 'defaultTimeout')) {
    this._addToQueue(message, type, timeout);
  },

  clearMessages() {
    let flashes = get(this, 'queue');

    flashes.clear();
  },

addMessage is responsible for creating flash messages where the user wishes to have a type that isn’t one of the default four, and clearMessages clears the array.

`_newFlashMessage`

  _newFlashMessage(service, message, type='info', timeout=get(this, 'defaultTimeout')) {
    Ember.assert('Must pass a valid flash service', service);
    Ember.assert('Must pass a valid flash message', message);

    return FlashMessage.create({
      type         : type,
      message      : message,
      timeout      : timeout,
      flashService : service
    });
  }

This private method is responsible for creating new flash message objects. A timeout is also set here, so we can remove the created flash message after a certain amount of time has elapsed.

The created flash message object also holds a reference to the singleton flash service, so that it can remove itself from the queue after the timeout has elapsed.

`_addToQueue`

  _addToQueue(message, type, timeout) {
    let flashes = get(this, 'queue');
    let flash   = this._newFlashMessage(this, message, type, timeout);

    flashes.pushObject(flash);
  },

This private method creates a new flash message object, then pushes it into the queue.

The Flash Message Object

View full gist

This Ember Object represents a single flash message.

Props

  isSuccess      : computed.equal('type', 'success'),
  isInfo         : computed.equal('type', 'info'),
  isWarning      : computed.equal('type', 'warning'),
  isDanger       : computed.equal('type', 'danger'),

  defaultTimeout : computed.alias('flashService.defaultTimeout'),
  queue          : computed.alias('flashService.queue'),

These are convenience properties using Ember.computed macros.

On init

  destroyLater: function() {
    let defaultTimeout = get(this, 'defaultTimeout');
    let timeout        = getWithDefault(this, 'timeout', defaultTimeout);

    run.later(this, '_destroyMessage', timeout);
  }.on('init'),

When the Object’s create method is called, init runs and calls _destroyMessage on it after the timeout period has passed.

Destroying the message

  destroyMessage() {
    this._destroyMessage();
  },

  // private
  _destroyMessage() {
    set(this, 'isDestroyed', true);
    get(this, 'queue').removeObject(this);
  }

Calling _destroyMessage sets the isDestroyed flag on the message, and removes itself from the queue. We also expose destroyMessage so that the flash message can be destroyed from the component itself.

Injecting the Flash Messages Service into Ember Controllers

Now that we have a service that holds a queue of flash messages, we’ll need to inject it into all our Controllers and Routes, so we can easily add new flash messages from across the app. We register the factory as a singleton, as we only want one instance of the service.

For more information about dependency and service lookups, check out the Ember guides.

import FlashMessagesService from 'ember-cli-flash/services/flash-messages-service';

export function initialize(_container, application) {
  application.register('service:flash-messages', FlashMessagesService, { singleton: true });
  application.inject('controller', 'flashes', 'service:flash-messages');
  application.inject('route', 'flashes', 'service:flash-messages');
}

export default {
  name: 'flash-messages-service',
  initialize: initialize
};

Rendering Flash Messages with a Component

With the service created, we can render all our flash messages into our application template. We’ll wrap it in a very simple component, which adds classes needed for Bootstrap to style ‘alerts’.

{{#if template}}
  {{yield}}
{{else}}
  {{flash.message}}
{{/if}}

import Ember from 'ember';

const { computed, get } = Ember;

export default Ember.Component.extend({
  classNames:        [ 'alert', 'flashMessage' ],
  classNameBindings: [ 'alertType' ],

  alertType: computed('flash.type', function() {
    let flashType = get(this, 'flash.type');

    return `alert-${flashType}`;
  }),

  flashType: computed('flash.type', function() {
    let flashType = get(this, 'flash.type');

    return flashType.classify();
  }),

  click() {
    let flash = get(this, 'flash');

    flash.destroyMessage();
  }
});

Now we can render our flash messages easily into any template:

{{#each flash in flashes.queue}}
  {{flash-message flash=flash}}
{{/each}}

You can also pass in your own template for the flash message if you wish:

{{#each flash in flashes.queue}}
  {{#flash-message flash=flash}}
    <h6>{{flash.flashType}}</h6>
    <p>{{flash.message}}</p>
  {{/flash-message}}
{{/each}}

Implementing this yourself is quite simple, but if you’d rather not, please install the ember-addon!

$ ember install:addon ember-cli-flash

or:

$ npm install --save ember-cli-flash

Ember.js — Detecting if a DOM Element is in the Viewport

Fri, 21 Nov 2014 14:27:45 GMT

Detecting whether or not an element is visible in the viewport is very useful when it comes to triggering animations or events. Before you drop in another jQuery plugin though, have a look at how easy it is to create a Mixin that you can add to any View or Component. Once added, you can simply ask that element if it’s in the viewport using the property the Mixin injects.

Let’s get started!

JS Bin Demo

InViewportMixin

I’ll first show the entire mixin, and then walk through each logical section. The idea is essentially to make use of the getBoundingClientRect method on each element to get the details of the element’s position relative to the viewport. We then compare this to the window’s innerHeight and innerWidth to determine whether or not the element is in the viewport. To keep things reactive, we bind the scroll event to update the element’s new position in the viewport.

getBoundingClientRect — The amount of scrolling that has been done of the viewport area (or any other scrollable element) is taken into account when computing the bounding rectangle.

Full Gist

import Ember from 'ember';

export default Ember.Mixin.create({
  scrollTimeout:      100,
  boundingClientRect: 0,
  windowHeight:       0,
  windowWidth:        0,

  enteredViewport: Ember.computed('boundingClientRect', 'windowHeight', 'windowWidth', function() {
    var rect, windowHeight, windowWidth;
    rect =         this.get('boundingClientRect');
    windowHeight = this.get('windowHeight');
    windowWidth =  this.get('windowWidth');
    return (
      rect.top >= 0 &&
      rect.left >= 0 &&
      rect.bottom <= windowHeight &&
      rect.right <= windowWidth
    );
  }),

  exitedViewport: Ember.computed.not('enteredViewport'),

  _updateBoundingClientRect: function() {
    var el;
    el = this.$()[0];
    this.set('boundingClientRect', el.getBoundingClientRect());
  },

  _setup: (function() {
    return Ember.run.scheduleOnce('afterRender', this, function() {
      this._updateBoundingClientRect();
      this.set('windowHeight', window.innerHeight || document.documentElement.clientHeight);
      this.set('windowWidth', window.innerWidth || document.documentElement.clientWidth);
    });
  }).on('didInsertElement'),

  _scrollHandler: function() {
    return Ember.run.debounce(this, '_updateBoundingClientRect', this.get('scrollTimeout'));
  },

  _bindScroll: (function() {
    var scrollHandler;
    scrollHandler = this._scrollHandler.bind(this);
    Ember.$(document).on('touchmove.scrollable', scrollHandler);
    Ember.$(window).on('scroll.scrollable', scrollHandler);
  }).on('didInsertElement'),

  _unbindScroll: (function() {
    Ember.$(window).off('.scrollable');
    Ember.$(document).off('.scrollable');
  }).on('willDestroyElement')
});

Getting the Details we Need

scrollTimeout:      100,
boundingClientRect: 0,
windowHeight:       0,
windowWidth:        0,

_updateBoundingClientRect: function() {
  var el;
  el = this.$()[0];
  this.set('boundingClientRect', el.getBoundingClientRect());
},

_setup: (function() {
  return Ember.run.scheduleOnce('afterRender', this, function() {
    this._updateBoundingClientRect();
    this.set('windowHeight', window.innerHeight || document.documentElement.clientHeight);
    this.set('windowWidth', window.innerWidth || document.documentElement.clientWidth);
  });
}).on('didInsertElement'),

First, let’s setup the basic building properties we need in our view: scrollTimeout, boundingClientRect, windowHeight and windowWidth. Because it’s computationally expensive to listen to every single scroll event, we’ll set a sensible timeout to debounce the scroll handler. This basically means the handler will only be called every 100ms in our case.

Next, we need to setup the initial values (L#12) of the properties when the element is inserted into the page. Ember’s View#didInsertElement is called when the view has been inserted into the DOM, so we can hook into it to get the right details at the right time. To ensure that this fires only after the element has been rendered, we use Ember.run#scheduleOnce to schedule the update once in the afterRender queue. If you’re unfamiliar with how the Ember run loop works, I highly recommend reading EmberZone’s 50,000 foot overview.

When the element is rendered on the screen, we simply use jQuery (one of Ember’s dependencies) to get the DOM element of the view, then set the value of the boundingClientRect property to the element’s getBoundingClientRect() object.

Handling Scroll Events and Listeners

In order to update boundingClientRect every time the window is scrolled, we’ll need to setup some event listeners:

_scrollHandler: function() {
  return Ember.run.debounce(this, '_updateBoundingClientRect', this.get('scrollTimeout'));
},

_bindScroll: (function() {
  var scrollHandler;
  scrollHandler = this._scrollHandler.bind(this);
  Ember.$(document).on('touchmove.scrollable', scrollHandler);
  Ember.$(window).on('scroll.scrollable', scrollHandler);
}).on('didInsertElement'),

_unbindScroll: (function() {
  Ember.$(window).off('.scrollable');
  Ember.$(document).off('.scrollable');
}).on('willDestroyElement')

The _scrollHandler method debounces function calls to _updateBoundingClientRect (defined earlier) based on the scrollTimeout we set initially. This is because running the method on every single scroll event is expensive, and we don’t really need to be that responsive.

We’ll want to keep the timeout between 100 — 300ms, so users perceive it as nearly instantaneous.

_bindScroll and _unbindScroll creates and destroys our scroll listener when the element is inserted, and when it is destroyed. Unbinding listeners is good practice, otherwise you’ll cause memory leaks in your app.

Exposing the Public API to Views and Components

Now that we’ve created the logic for our mixin, it’s time to let our API be consumed by the Views or Components we want to track.

enteredViewport: Ember.computed('boundingClientRect', 'windowHeight', 'windowWidth', function() {
  var rect, windowHeight, windowWidth;
  rect =         this.get('boundingClientRect');
  windowHeight = this.get('windowHeight');
  windowWidth =  this.get('windowWidth');
  return (
    rect.top >= 0 &&
    rect.left >= 0 &&
    rect.bottom <= windowHeight &&
    rect.right <= windowWidth
  );
}),

exitedViewport: Ember.computed.not('enteredViewport'),

The idea is essentially to make use of the getBoundingClientRect method on each element to get the details of the element’s position relative to the viewport.

enteredViewport is a computed property that determines whether or not the element is inside the viewport. We observe the three properties we set initially, so that the computed property updates when their values change. If you have a read of the API for getBoundingClientRect(), you’ll realize that an element is in the viewport when it’s bottom and right values are within the window’s innerHeight/width. This returns a boolean value, that we can then use in our Views or Components.

exitedViewport is a computed property macro that simply inverses another property after coercing it into a boolean value.

With these APIs, we can now do some interesting things when an element enters or leaves the viewport!

Consuming the Mixin

With Ember, reusable mixins are easy to use. Here’s the example I made in my JS Bin:

App.ThisIsDogComponent = Ember.Component.extend(App.InViewportMixin, {
  classNames:        ['dog-card'],
  classNameBindings: ['enteredViewport:entered-viewport']
});

With the mixin added, you can use enteredViewport and exitedViewport like any other property in your View or Component.

The component I made in my JS Bin renders a card with a dog breed and some filler description, and its style updates when the cards enter the viewport. It’s a simple example, but it should give you an idea of what you can do with this. You could have animations fire, or you could perform certain logic when something enters the viewport.

I hope you’ve enjoyed reading! If you have any questions, you can tweet me or leave a note on this post.

Ember – Simple text search computed property macro

Wed, 19 Nov 2014 10:48:11 GMT

Every now and then, you want to let your users quickly search for records that you’ve already loaded into your store. We can easily implement naïve search using Ember’s Array#filter and native String prototype methods, but let’s go a little step further and create a custom computed property macro (CPM) that wraps the search so we can easily drop it into other properties.

Source: Unsplash | By Todd Quackenbush

Demo

JSBin

The search macro

utils/computed/search.js

import Ember from 'ember';
var computed = Ember.computed;

export default function search(dependentKey, propertyKey, searchQueryKey, returnEmptyArray) {
  returnEmptyArray = (typeof returnEmptyArray === "undefined") ? false : returnEmptyArray;
  return computed("" + dependentKey + ".@each." + propertyKey, searchQueryKey, function() {
    var items, query;
    if (returnEmptyArray && !this.get(searchQueryKey)) {
      return Ember.A([]);
    }

    query = this.get(searchQueryKey) || '';
    query = query.toLowerCase();
    items = this.get(dependentKey) || Ember.A([]);

    return items.filter(function(item) {
      if (item.get(propertyKey)) {
        return item.get(propertyKey).toLowerCase().indexOf(query) !== -1;
      }
    });
  });
}

Our search macro returns an outer function (line#5) that takes 4 arguments, a dependentKey, a propertyKey, a searchQueryKey and a returnEmptyArray argument.

The dependentKey (e.g. users) and propertyKey (e.g. ‘fullName’) relates to the array we want to search through. We specify a searchQueryKey so that we can update the results of our macro when the search term changes. The last argument is optional, and isn’t critical – it returns an empty array (line#9) if no query is entered.

The outer function returns an inner function (line#7), which is actually just an Ember.computed property that observes the properties we specified in the outer function. If this syntax seems unusual to you, it uses the alternate invocation and not the function prototype method.

Using the special key @each, we can make sure that Ember observes the propertyKey on each item in our array so that it can search through it correctly.

Finally, after slightly massaging the inputs (lines#13–15), we just return the filtered array (line#17) using String.prototype.indexOf. While this search is naïve and probably won’t perform too well on large datasets, with our computed property macro it is very easy to implement something more efficient.

Using the computed property macro

Now we can very quickly and easily drop in text search on any of our controllers or components:

import computedSearch from '../utils/computed/search';

export default Ember.ArrayController.extend({
  searchQuery:   null,
  searchResults: computedSearch('model', 'fullName', 'searchQuery')
});

By simply binding searchQuery to the value of any input or textarea, we’re able to drop in live search on data in the store very easily.

It’s a good idea to have a look at your application to see if you find yourself repeating bits of functionality, and create custom property macros so you can move shared logic into one place. This DRYs up your code and makes it much more testable, which is probably a good thing.

Thanks for reading!

Slack-style loading messages in an Ember app

Sat, 15 Nov 2014 00:21:24 GMT

If you haven’t used Slack already, it’s an awesome chat app for teams that’s similar to IRC. I’ve been using it for a while now, and I’ve pretty much sworn off writing emails for internal communication in favour of Slack.

One little interaction that I particularly enjoy is the random loading message that appears every time you load the app – it’s a nice little touch that makes the app feel just a little bit more human and fun.

Because Ember is well designed for asynchronous routing, it’s really easy to add application loading messages by making use of the little known global loading route that you get for free. Let’s get started!

What We’re Building

What you see when you open the Slack app

We’re going to create a few things:

A loading message component
A custom computed property macro (CPM) for randomly choosing an item from an array (e.g. Ruby’s Array#sample)
CSS for animating the ellipsis

The Component

import Ember from 'ember';
import { sample: computedSample } from '../macros/computed/sample';

var { computed } = Ember;

export default Ember.Component.extend({
  tagName              : 'h1',
  classNames           : [ 'loading', 'animated', 'fadeIn' ],
  showLoadingMessages  : false,
  randomLoadingMessage : computedSample('loadingMessages'),
  loadingText          : 'Loading',

  loadingMessages: [
    'A day without sunshine is like, you know, night.',
    'My fake plants died because I did not pretend to water them.',
    'Weather forecast for tonight: dark.'
  ]
});

The component itself is fairly simple – we’re setting a tag name and some classes (I’m using animate.css to fade the message in), as well as some loading messages and text. In addition, we accept a simple boolean property to show or hide the random loading messages, as sometimes we might only want the ‘Loading…” text to appear. The only thing of interest here is the computedSample CPM, which is defined in a little utility file.

A Custom Computed Property Macro

import Ember from 'ember';

var { computed, getWithDefault } = Ember;

export default function(dependentKey) {
  return (
    computed(`${dependentKey}.@each`, function() {
      var emptyArray = Ember.A([]);
      var items      = getWithDefault(this, dependentKey, emptyArray);
      var length     = items.get('length');
      var randomItem = items[Math.floor(Math.random() * length)];

      return randomItem || '';
    })
  ).volatile();
};

Here, we’re creating a new computed property macro for sampling an array and returning a random item.

What this function does is return an Ember.computed function that’s observing each item in some dependentKey (an array), then accessing a random index on that array. The prototype method volatile tells Ember not to cache the return value, so we get a unique loading message each time the app enters the loading route (even without a hard refresh).

Animating the ellipsis in CSS

i.ellipsis i {
  font-style: normal;
  opacity: 0;
  -webkit-animation: dot 1.3s infinite;
  -webkit-animation-delay: 0s;
  -moz-animation: dot 1.3s infinite;
  -moz-animation-delay: 0s;
  -o-animation: dot 1.3s infinite;
  -o-animation-delay: 0s;
  animation: dot 1.3s infinite;
  animation-delay: 0s;
}

i.ellipsis i+i {
  opacity: 0;
  -webkit-animation: dot 1.3s infinite;
  -webkit-animation-delay: 0.2s;
  -moz-animation: dot 1.3s infinite;
  -moz-animation-delay: 0.2s;
  -o-animation: dot 1.3s infinite;
  -o-animation-delay: 0.2s;
  animation: dot 1.3s infinite;
  animation-delay: 0.2s;
}

i.ellipsis i+i+i {
  opacity: 0;
  -webkit-animation: dot 1.3s infinite;
  -webkit-animation-delay: 0.3s;
  -moz-animation: dot 1.3s infinite;
  -moz-animation-delay: 0.3s;
  -o-animation: dot 1.3s infinite;
  -o-animation-delay: 0.3s;
  animation: dot 1.3s infinite;
  animation-delay: 0.3s;
}

@-webkit-keyframes dot {
  0%, 50% {
    opacity: 0;
  }
  100% {
    opacity: 1;
  }
}


@-moz-keyframes dot {
  0%, 50% {
    opacity: 0;
  }
  100% {
    opacity: 1;
  }
}

@-o-keyframes dot {
  0%, 50% {
    opacity: 0;
  }
  100% {
    opacity: 1;
  }
}


@keyframes dot {
  0%, 50% {
    opacity: 0;
  }
  100% {
    opacity: 1;
  }
}

The above lets us animate the opacity of each individual dot in the ellipsis. Using sibling selectors, we can easily apply a different delay to each dot, and then have the keyframes repeat infinitely.

Using the component

{{loadingText}}
<i class="ellipsis">
  <i>.</i>
  <i>.</i>
  <i>.</i>
</i>

{{#if showLoadingMessages}}
  <small>{{randomLoadingMessage}}</small>
{{/if}}

The template for the component.

<div class="loading-wrapper">
  {{loading-message showLoadingMessages=true}}
</div>

The loading template that’s rendered in the loading route.

The Final Product

The finished product

In Closing

Ember makes front end development such a joy. I hope you’ve enjoyed how easy it is to add Slack-like loading messages into your app!

Using Highcharts.js in an Ember app

Thu, 13 Nov 2014 14:46:31 GMT

Highcharts is one of the better supported and developed front end charting libraries out there, and it makes creating standard charts a breeze. If you have a custom chart the likes of which the world has never seen however, you might be better off building it in something like D3.js. If all you need is a vanilla chart in your Ember app, read on.

Implementing Highcharts in your Ember application so that it live binds to your data is simple, and really highlights the power of Ember.

The component and theme mixin

component.js

App.HighChartsComponent = Ember.Component.extend(App.HighchartsThemeMixin, {
  classNames:   [ 'highcharts-wrapper' ],
  content:      undefined,
  chartOptions: undefined,
  chart:        null,

  buildOptions: Em.computed('chartOptions', 'content.@each.isLoaded', function() {
    var chartContent, chartOptions, defaults;
    chartOptions = this.getWithDefault('chartOptions', {});
    chartContent = this.get('content.length') ? this.get('content') : [
      {
        id: 'noData',
        data: 0,
        color: '#aaaaaa'
      }
    ];
    defaults = {
      series: chartContent
    };
    return Em.merge(defaults, chartOptions);
  }),

  _renderChart: (function() {
    this.drawLater();
    this.buildTheme();
  }).on('didInsertElement'),

  contentDidChange: Em.observer('content.@each.isLoaded', function() {
    var chart;
    if (!(this.get('content') && this.get('chart'))) {
      return;
    }
    chart = this.get('chart');
    return this.get('content').forEach(function(series, idx) {
      var _ref;
      if ((_ref = chart.get('noData')) != null) {
        _ref.remove();
      }
      if (chart.series[idx]) {
        return chart.series[idx].setData(series.data);
      } else {
        return chart.addSeries(series);
      }
    });
  }),

  drawLater: function() {
    Ember.run.scheduleOnce('afterRender', this, 'draw');
  },

  draw: function() {
    var options;
    options = this.get('buildOptions');
    this.set('chart', this.$().highcharts(options).highcharts());
  },

  _destroyChart: (function() {
    this._super();
    this.get('chart').destroy();
  }).on('willDestroyElement')
});

mixin.js

App.HighchartsThemeMixin = Ember.Mixin.create({
  buildTheme: function() {
    Highcharts.theme = {
      colors: [
        '#258be2',
        '#666666',
        '#f45b5b',
        '#8085e9',
        '#8d4654',
        '#7798bf',
        '#aaeeee',
        '#ff0066',
        '#eeaaee',
        '#55bf3b',
        '#df5353',
        '#7798bf',
        '#aaeeee'
      ],
      chart: {
        backgroundColor: null,
        style: {
          fontFamily: "'Helvetica Neue', 'Helvetica', 'Arial', sans-serif"
        }
      },
      title: {
        style: {
          color: 'black',
          fontSize: '18px',
          fontWeight: 'bold'
        }
      },
      subtitle: {
        style: {
          color: 'black'
        }
      },
      tooltip: {
        borderWidth: 0,
        style: {
          fontSize: '16px'
        }
      },
      legend: {
        itemStyle: {
          fontWeight: 'bold',
          fontSize: '14px'
        }
      },
      xAxis: {
        labels: {
          style: {
            color: '#6e6e70',
            fontSize: '16px'
          }
        },
        title: {
          style: {
            fontSize: '14px'
          }
        }
      },
      yAxis: {
        labels: {
          style: {
            color: '#6e6e70',
            fontSize: '16px'
          }
        },
        title: {
          style: {
            fontSize: '14px'
          }
        }
      },
      plotOptions: {
        series: {
          shadow: true
        },
        candlestick: {
          lineColor: '#404048'
        }
      },
      navigator: {
        xAxis: {
          gridLineColor: '#D0D0D8'
        }
      },
      rangeSelector: {
        buttonTheme: {
          fill: 'white',
          stroke: '#C0C0C8',
          'stroke-width': 1,
          states: {
            select: {
              fill: '#D0D0D8'
            }
          }
        }
      },
      scrollbar: {
        trackBorderColor: '#C0C0C8'
      },
      background2: '#E0E0E8',
      global: {
        timezoneOffset: new Date().getTimezoneOffset()
      }
    };
    return Highcharts.setOptions(Highcharts.theme);
  }
});

Private and public APIs

The component defines three properties as APIs – content, which refers to series data in a form that Highcharts expects, chartOptions, a POJO that defines options for Highcharts (see API) and chart, a private property that holds the actual Highchart object so that we can refer to it within the component.

didInsertElement

When the component’s didInsertElement hook fires, we call two methods: drawLater(), and buildTheme().

buildTheme() is a method from the Highcharts theme mixin that simply applies theme options to the Highchart object. drawLater() runs the draw() method once in the afterRender queue in the Ember run loop, which makes sure the DOM elements are rendered before we attempt to wire up our Highchart.

Setting Highcharts options

In the method buildOptions, we add a default data series to be displayed if no content ends up being passed into the component. You could very easily set this up to include your own global Highcharts options.

Binding live data changes to the Highchart

With contentDidChange we set up an Ember observer on the content that’s been passed into the component. We make use of a handy Highcharts API method that lets us update the data for a series (without redrawing the entire chart), so that the chart doesn’t trash the DOM by re-rendering multiple times when data changes. This is all you need to do to get data live binding into Highcharts!

Teardowns

Finally, for performance issues, we want to teardown and destroy the chart when the component is destroyed. This is easily achieved with the Ember lifecycle hook willDestroyElement, which fires when the component is about to be destroyed (but not yet).

Using the component in your templates

Using the Highcharts component is as simple as:

{{high-charts content=someController.chartData chartOptions=someController.chartOptions class="some-custom-class"}}

As you can see, it’s really easy to integrate Highcharts into your Ember application. It’s not free if you’re building a non-personal project, but the support from the Highcharts team is amazing and they update the library very frequently.

If you want to build custom charts that aren’t already implemented in Highcharts, I’d highly recommend looking into D3.js. A post on wrapping D3.js might be next if enough people tweet me about it.

Enjoy!

Ember.js and HTML5 Drag and Drop

Thu, 25 Sep 2014 02:38:31 GMT

It’s fairly trivial to add a ‘drag and drop’ interface to Ember.js with html5, without the need for external libraries, although the caveat is that mobile browsers don’t (yet) support html5 drag and drop.

The basic premise is to create 2 components:

a draggable-dropzone component, that handles when an item is dropped into it (e.g. a shopping cart)
a draggable-item component, that sets up the data transfer into the dropzone

Using transclusion, we can then easily add our ‘drag and drop’ functionality into our Ember application with different UI.

demo (with extra bells and whistles)

Code: JSBin demo

via Gfycat

draggable-dropzone

Let’s first define our draggable-dropzone component:

import Ember from 'ember';

var { set } = Ember;

export default Ember.Component.extend({
  classNames        : [ 'draggableDropzone' ],
  classNameBindings : [ 'dragClass' ],
  dragClass         : 'deactivated',

  dragLeave(event) {
    event.preventDefault();
    set(this, 'dragClass', 'deactivated');
  },

  dragOver(event) {
    event.preventDefault();
    set(this, 'dragClass', 'activated');
  },

  drop(event) {
    var data = event.dataTransfer.getData('text/data');
    this.sendAction('dropped', data);

    set(this, 'dragClass', 'deactivated');
  }
});

{{yield}}

Ember includes built-in events for the html5 drag and drop API, so we can make use of them right out of the box. We also set up a classNamebinding to provide visual cues to our user that the element is a dropzone for dragging things into.

draggable-item

Next, we define the component for setting up items to be draggable:

import Ember from 'ember';

var { get } = Ember;

export default Ember.Component.extend({
  classNames        : [ 'draggableItem' ],
  attributeBindings : [ 'draggable' ],
  draggable         : 'true',

  dragStart(event) {
    return event.dataTransfer.setData('text/data', get(this, 'content'));
  }
});

{{yield}}

draggable is, as you’d expect, the attribute that makes a DOM node draggable. We simply set the attribute of the component, and handle the dragStart event to get the content of the component. Unfortunately, the HTML5 API does not allow for draggables to transfer JavaScript, so we’ll have to perform a workaround.

Using the components in our application

One thing to note is that we can’t transfer actual objects or records through the API, so when we include the component into our template, we have to set its content to the record’s ID.

Here’s a simple example of an interface for adding users to a new ‘team’ record we want to save:

<div class="selected-users">
  {{#draggable-dropzone dropped="addUser"}}
    <ul class="selected-users-list">
      {{#each user in selectedUsers}}
        <li>{{user.fullName}}</li>
      {{/each}}
    </ul>
  {{/draggable-dropzone}}
</div>

<div class="available-users">
  {{#each user in users}}
    {{#draggable-item content=user.id}}
      <span>{{user.fullName}}</span>
    {{/draggable-item}}
  {{/each}}
</div>

If you recall, we sent an action on drop in the draggable-dropzone component:

drop(event) {
  // ...
  this.sendAction('dropped', data);
}

Now we simply need to define an appropriate action on our controller to handle the drag and drop:

import Ember from 'ember';

var { computed, get } = Ember;

export default Ember.ArrayController.extend({
  selectedUsers        : Ember.A([]),
  remainingUsers       : computed.setDiff('model', 'selectedUsers'),
  remainingUsersLength : computed.alias('remainingUsers.length'),

  actions: {
    addUser(userId) {
      var selectedUsers = get(this, 'selectedUsers');
      var user          = get(this, 'model').findBy('id', parseInt(userId));

      if (!selectedUsers.contains(user)) {
        return selectedUsers.pushObject(user);
      }
    },

    addAllUsers() {
      var remainingUsers = get(this, 'remainingUsers')
      return get(this, 'selectedUsers').pushObjects(remainingUsers);
    },

    removeUser(user) {
      return get(this, 'selectedUsers').removeObject(user);
    },

    removeAllUsers() {
      return get(this, 'selectedUsers').clear();
    }
  }
});

In our Controller, we simply find the appropriate user record from the store (using the userId we get from the draggable-item component), and then push it into an array called selectedUsers. We can then do whatever we want with this array (e.g. create a new team with the selected users).

Some basic styling:

$default-margin : 20px;
$gray-light     : #e1e1e1;
$gray-medium    : #aaa;
$green          : #2ecc71;
$white          : #fff;
$black          : #111;

.draggableDropzone {
   display: block;
   border: 3px dashed $gray-medium;
   padding: $default-margin / 2;
   width: 100%;
   min-height: $default-margin * 2.5;
   color: $gray-medium;
   margin-bottom: $default-margin / 2;
   &.activated {
     border-color: $green;
   }
   &.deactivated {
     border-color: $gray-light;
   }
}

.draggableItem[draggable=true] {
   display: inline-block;
   min-width: $default-margin;
   min-height: $default-margin;
   background: $gray-light;
   padding: $default-margin / 4 $default-margin / 2;
   margin: $default-margin / 4;
   -moz-user-select: none;
   -khtml-user-drag: element;
   cursor: move;
   &:hover {
     background-color: $gray-medium;
   }
}

Over at doceo, we’ve added more functionality to the interface, including typeahead search, and other useful controls (add all users, removing all users, removing a single user). This basic setup is sufficient enough to handle most use cases for a drag and drop UI, and having transclusion (yield) lets us define different designs for the same drag and drop functionality.

Special thanks to @itscatkins for pairing with me for this one.

no.lol

This Time Is Different

Best practice today, anti-pattern tomorrow

This time is no different

Does It Spark Joy?

Does it spark joy?

What’s next

Type Narrowing in TypeScript

Being precise helps TypeScript help you

Type narrowing with assertion functions

Type narrowing with type guards

Conclusion

#2 Maximizing Success in Engineering Interviews

Before you begin

What do interviewers look for?

How do I demonstrate that I can do the job?

Work the question

Collaborate and share context

Compare the tradeoffs

Be honest

Do I raise the bar?

Being successful in a company’s culture

Ugh

Migrating from Medium to Gatsby

Exporting your content off of Medium

Getting started with Gatsby

Setting up

How does Gatsby even?

Automate all the things

Deploying your blog with Netlify

Add the lighthousebot for continuous performance testing

Bring on the bots

#1 Should I Become a Tech Lead?

What does a tech lead do anyway?

The Voight Kampff Test for Engineering Managers

There are only 2 types of decisions

Growing as an engineer

Exploring the Strongly Typed Graph

Move fast and learn things

Everything is a graph

Move fast and grow the network

End-to-end type coverage

Highly Aligned, Loosely Coupled

Schema registry

Domain graph

How does this work in practice?

Commit to Commit

Move forward without hesitation

An Engineer’s Guide to Communication

“Computers are easy; people are hard”

Listen first, understand second, speak last

Communicating non-violently

Skeleton Screen Loading in Ember.js

Don’t fetch your data in the route

Move data loading out of your route

ember-concurrency saves the day

Data loading with query params

What should I use the route for?

I Am Still Learning

I’m afraid

I’m still learning

Learning from fear

Rise From the Ashes — Incremental APIs With Phoenix

Discovery

Terraforming the legacy API

What about performance?

Give it a spin

Component dependency injection in Ember.js

Component Dependency Injection

Not my concern

Bringing Ecto Changesets into Ember.js

Ecto Changesets to the Rescue

Changesets in Ember

Virtual Properties with unknownProperty and setUnknownProperty

Storing Changes

Data Down Actions Up, Not 2-Way Bindings

Is This Real Life?

Validating Changesets

The Only Constant is Change

Declarative Templating in Ember with Composable Helpers