Category Archives: Cook Smarts

Rails and external services: allow for failure

At Cook Smarts we rely on external services for payments, image processing, and more. Sometimes, the app will fail to reach a service. Perhaps the service is down or there’s a network error somewhere along the line.

How can we tolerate such errors with a minimum impact to the user?

Here’s an example of how we addressed a recurring error with an external service:

A user can export a recipe as a PDF, including an image of the meal.* We retrieve the appropriately-sized image form reSRC, our external image processor.

PDF exported recipe from Cook Smarts

Occasionally, the connection to retrieve the image times out, preventing the image from importing into the PDF. Before, this caused an exception, preventing the user from exporting the recipe at all.

For a better user experience, we now show a friendly error message in place of the image.

Exported PDF recipe from Cook Smarts with image error message

To show the friendly error instead of a fatal exception, we use ‘begin’ and ‘rescue’ in Ruby, in the midst of our Prawn PDF code.

Fault tolerance is crucial when using external services. Assume that your app and the services will clash sometimes, and plan accordingly.

* Eventually, we’ll cache these PDF’s, but for now they are generated whenever a user requests them.

A smarter nutrition label for the web

Ah, the humble nutrition label. Since it was introduced in the 1990’s (in the U.S., anyway), it’s been pretty much ubiquitous. We see them everywhere, whether we understand them or not.

They’re particularly puzzling on foods with multiple ingredients. Looking at a nutrition label and an ingredients list side-by-side, you might guess which ingredients contribute the most to each nutrient, but you may be wrong.

Why am I talking about nutrition on a web development blog?

We implemented nutrition labels for Cook Smarts meal planning app, and put a twist on the classic. In addition to showing a nutrition label for every recipe, we show which ingredients contribute the most to each nutrient.

For instance, below are the nutrition facts for Orange-Sesame Beef Stirfry. By expanding the total fat, I can see that the #1 and #2 contributors are the flank steak and the cooking oil.

If I were counting carbs, I could expand total carbs and perhaps cut back on the rice.

Nutrition label shows which ingredients contribute most to each nutrient

Since we integrated the USDA’s robust nutrition database into Cook Smarts’ recipe editor on the back-end, we had this per-ingredient data. Instead of just exposing the recipe’s total nutrition facts, we tried to think of ways to go a little deeper. This is our first attempt at doing so!

The USDA database is huge, so we brought it onto a separate server that we interface with using our own API. It’s working well, and keeping the extra load off of Cook Smarts’ primary app server. More on our first attempt at service-oriented architecture soon!

Special thanks to Chris Coyier for his nutrition label HTML and CSSMatt Beedle for his USDA nutrient database gem, and Cameron Dutro for his Active Nutrition gem.

Sending Mandrill e-mails from Rails, the MVC way

Update: For updated guidance, see E-mail in Rails with MailChimp and Mandrill, a comprehensive guide

Mandrill is a transactional e-mail service for developers. It allows you to quickly reach out to users from your app via e-mail, through SMTP or Mandrill’s  API.

Cook Smarts‘ transactional e-mails sometimes go to many users at once, and we quickly hit the limits of SMTP. It was time to use Mandrill’s API to send out e-mails from our Rails app.

Here’s how we moved from ActionMailer/SMTP to Mandrill’s API while staying true to the model-view-controller (MVC) nature of Rails.

Install the Mandrill gem

Add the Mandrill API to your gemfile.

Then run ‘bundle install’ from the same directory.

Send e-mail

Want the simple version of the code needed to send a message? Check out Mandrill’s documentation.

Below we’re going to cover Cook Smarts’ more complex use case.

We specify the subject, from name, and from e-mail above, which is pretty self-evident.

But – surprise! – we’re sending this particular e-mail to a ton of users at once, and we want to address each user by name.

Addressing the message

This message is going to all users with a subscription. We have a scope in our User class called ‘paid,’ which returns all the paid users.

We need to get these users’ e-mail addresses into an array for Mandrill. A class method, User.to_mandrill_to, takes care of this.

When we call ‘User.to_mandrill_to(User.paid),’ we get all our paid users’ e-mail addresses back as an array.

Merge tags

Mandrill uses merge tags to personalize messages. For instance, we want to say “Dear Mary” if the message is to Mary, and “Dear John” if it’s to John.

When we send multiple messages at once, we need to tell Mandrill which name is related to which e-mail address.

Our e-mail template, stored in a Rails view, contains a placeholders for the user’s name:

Another class method, User.to_mandrill_merge_vars, associates each user’s e-mail address with their first name:

This gets us the value we need for the ‘merge_vars’ argument of the API request above.

The message

As stated earlier, the e-mail template lives as a view in our Rails app.

We’ll use render_to_string to process the template and insert it into our API request.

The view should be a full HTML page, including and tags. We add ‘:layout => false’ to avoid bringing in other header/footer content from our app.

Avoid an embarrassing mistake

Remember to include ‘:preserve_recipients => false’ in your API request, unless you want all the people you’re e-mailing to appear in the To line in every message. Mandrill has the details.

MVC Summary

Our Users model provides the addressee information, the meal plan e-mail template/view provides the message, and the admin controller sends the actual e-mail.

All of this without the use of SMTP or Rails ActionMailer – just Mandrill’s API.

We’ve found that this solution has worked well for transactional e-mails with multiple recipients.

If you’re looking for tight Mandrill + ActionMailer integration, check out the Mandrill delivery method gem.

We’re starting a series called Mailing on Rails, which will cover all the bases to get you up and running with mail in your app. Want us to let you know when it’s up?

Responsive images and the beauty of food

Food is beautiful, and Cook Smarts has plenty of it to show. The service provides a meal plan each week, with high-res photos of each meal.

The Cook Smarts archive, where you can view previous meal plans, did not take advantage of the pictures. It was far too text-y.

The old, text-based archives
The old, text-based archives

We started to think of a better way to incorporate the photos, and came up with a design for each week of meals.

Sketch of the new visual archive

We also thought of a more engaging way to welcome people who were trying out the service, with a personal message from Jess.

Sketch of call to action

Here’s how it actually came out:

New, visual archives

We faced a lot of challenges putting this together. Here are a few, and we how we solved them:

Respecting the user’s bandwidth

It was important to minimize load time, particularly for mobile users.

We used reSRC to serve the appropriate image size for each device, without having to generate thumbnails ourselves.

It saved a ton of time, and I encourage graphics-heavy site owners to check it out. Here’s a screencast showing reSRC in action.

Adjusting for mobile

Four images in one row would not work on mobile, so we went from four columns to one.

But the images were too tall. One meal took up nearly the entire iPhone screen, making it time-consuming to scroll through all of the plans.

Tall images make it time-consuming to scroll through meal plans on mobile

Too much scrolling!

Then someone had a genius idea: on mobile, show a slice from the middle of the image. You still got the idea, with far less scrolling. You can see the full image after clicking the meal.

Center-cropped images make it faster to scroll on mobile

By adding a simple parameter to the reSRC image URL, we cropped the images with the result above.

https://app.resrc.it/s=w400/c=w400,h133/http://cooksmartsapp.s3-us-west-2.amazonaws.com/meal_photos/20130115-FishTacos-04.jpg

In the reSRC image URL, we set the image’s width to 400px, and took a 133px slice through the middle of it.

Surely, we could also have done this with a tool on our server like ImageMagick, but using reSRC was faster than rolling our own thumbnails.

Showing different images on desktop and mobile

We had to find a way to load different images on desktop and mobile, in order to achieve the crop described above.

Image tags don’t support image swapping without JavaScript, so we instead used containers with background images. We applied media queries to the containers to serve a different background image depending on the screen width.

The default image is regular size:

The mobile image is center-cropped version:

Separate CSS for each image

Each meal needed a separate background-image style. That’s a lot of styles!

In Rails, we dynamically generate the style tags and place them under a <style> tag on top of the archives.

At first, we tried a separate <style> tag for each image, but this bombed on IE 9 and below, which place a limit on the number of style sheets and tags.

Making the image fit its background container

Our site is responsive, so the image widths change based on the user’s screen size.

With regular image tags, you can simply say…

… and they will scale to their containers.

Background images are a little different. We had to use…

… on the meal containers, in order for the meal images to scale properly.

To support older browsers, we included the background-size polyfill, and confirmed that everyone worked well using BrowserStack (not cheap, but excellent).

Preventing jumping around while loading

Images won’t load right away, particularly on a phone.

Unless you specify the width and height of an image in advance, the page will jerk around as each image loads.

We don’t not know the width and height of the image in advance since the site is responsive, but we still wanted to avoid page jerk.

We do know the proportion of the photos (the relationship between width and height), so we used the padding-bottom technique from Smashing Magazine. With this technique, knowing the proportion has the same effect as knowing the exact width and height, leaving the proper amount of room for the images before they load and eliminating page jerk.

On desktop:

… and on mobile, which is a bit different since we’re only taking a center crop:

To get the proportion (the % above), we divided the height by the width and multiplied by 100. The proportion is always the same no matter the image’s width.

In closing, content is paramount

Web projects are much more achievable when the content is great. In this case, I was lucky to have beautiful pictures of food. Had Jess not taken pictures of every Cook Smarts meal from the beginning, the visual archives would not have launched as quickly.

Want a screencast about the techniques above? Please leave a comment and let me know, or tweet me @coreyITguy.

To see the archives in their glory, sign up for a test drive account on Cook Smarts.

Using Zurb Foundation’s grid for a responsive redesign, with three tweaks

This is the first in a series of articles about the Cook Smarts redesign.  Try their meal plan service to experience the redesign for yourself.

The key to responsive design is the grid. Arranging your content in a grid makes it easier to determine how it responds to various screen sizes.

The concept is pretty simple, but execution can get dicey.

It’s perfectly possible to roll your responsive grid, and everyone should learn how. However, developers have taken the time to create and share grid systems that work for most web sites.

Zurb Foundation is one of these pre-made grid systems that can save a lot of development time on responsive web projects. The Washington Post recently used it to revamp its online video site, Post TV.

We’ll step through Foundation’s grid, then apply it to the Cook Smarts responsive redesign.

Cook Smarts presents a week’s worth of meals on one page, with pictures and titles. Alongside the meals are notes for the week, such as what ingredients can be stretched across different recipes and what to sub for harder-to-find ingredients.

The previous, non-responsive site used a fixed grid.  It was great on desktop, but  not on a phone:

The Cook Smarts' web site on an iPhone, without responsive design

The text isn’t readable when it first comes up, so one has to scroll all around the page to get any use out of it. We’ll fix that using Zurb Foundation.

Meal plan on Cook Smarts, with responsive design

Above is the same page on a phone, once Foundation’s basic grid is applied. We had to do some legwork here to tell Foundation how our content should behave on small vs. large screens. For an overview of the basics, check out Foundation in 5 minutes.

In addition, we applied some tweaks that fall outside of Foundation’s default behavior.

Tweak 1: Distinguishable content boxes

The screenshot above has a single background color, making it difficult to distinguish different elements of the page. Google addresses this same issue by using white boxes with a gray background:

Google's mobile search screen, with a grey background and white boxes

Here’s how a similar effect looks on Cook Smarts:

Cook Smarts meal plan, with white content boxes added to the responsive design

The meals are easier to distinguish because they called out in white content boxes.

Here’s how the effect looks on desktop:

Cook Smarts meal plan on a desktop, with responsive design

We accomplished the gray/white effect by introducing our own class called cs-box.  It is simply a white box with a bit of shadow.  Because it is a block element (as div’s are by default), it stretches to the full width of its container. Its container is a Foundation column, so it behaves responsively without additional effort.

To recap, here’s how we coded the responsive grid above.

To contain the meals, we created a column that is 8/12th (2/3rd) the width of the page.

<div class="row">
<div class="large-8 columns">

Then we looped through each meal in Rails, outputting the following code for each. Notice that our class cs-box contains each meal, and each meal is presented in two columns of equal width – the picture and the meal description.

<div class="cs-box">
<div class=”large-6 columns meal-photo-wk”>
Image of meal
</div>
<div class=”large-6 columns day-info”>
Meal title and sub-title
</div>
</div>

Finally, we’ll put  some general information on the right side.  We’ll close out the 2/3rd-width column, and start a 1/3rd-width column.  Finally, we’ll close out the row altogether.

</div>
<div class=”large-4 columns>
<div class="cs-box">
<!-- Smarts from the team -->
</div>

<div class=”cs-box”>
<!-- Ideas for leftovers -->
</div>
</div>
</div>

Tweak 2: Take care of awkward screen sizes

We’re looking OK on a large desktop and a small phone, but the middle ground is looking a bit awkward. Maybe this is a smaller tablet or someone who prefers to keep a smaller browser window. In any case, we need to make sure Cook Smarts looks good on all screen sizes.

Here is a snapshot of a medium screen size:

Cook Smarts responsive meal plan looks a bit awkward on mid-size screens

Yikes! The image is huge! Foundation puts everything into one column for any screen width below 767px, but this just doesn’t look great with our content.

Ethan Marcotte said in a presentation that the trick to applying responsive design is deferring to your content. Well, our content is not loving our new grid at a middle screen size.

To fix this, we’ll put in some custom CSS to make the images look good on medium screen sizes.

@media only screen and (min-width: 30em) {
.meal-photo-wk, .day-info {
position: relative !important;
width: 50% !important;
}
}

This ensures that our image column remains at 50% width above 30em, a number we reached by experimentation (resizing the browser window to determine the range where things looked bad).

Now, our middle range looks much better:

A better mid-size view of a Cook Smarts meal plan

Tweak 3: Move stuff around on desktop vs. mobile

Back to working around our content.  We’ve used the Foundation grid on individual recipe pages, as well, and here’s how those are looking on desktop:

Cook Smarts responsive recipe

Here’s the problem.  The ingredients should appear before the Prep/Make/Review tabs when the screen is sized down. By default, Foundation will drop it below the tabs when the page becomes one column on a small screen.

Here’s where we can use Foundation’s source ordering, which can initially be confusing.

In the code, we will place ingredients first, which will make it appear on top of Prep/Make/Review on mobile. To make it appear after Prep/Make/Review on desktop, we will use push/pull as shown below.

<div class=”row”>
<div class=”large-4 columns push-8“>
<!– Ingredients –>
</div>
<div class=”large-8 columns pull-4“>
<!– Prep/Make/Review –>
</div>
</div>

The ingredients column is 4/12 columns wide, and appears first in the code. On a large screen, it should be pushed to the right side, instead of appearing on the left as it normally would.

The Prep/Make/Review column is 8/12 columns wide, appears second in the code. On a large screen, it should be pulled to the left, rather than appearing on the right as it normally would.

Responsive recipe on Cook Smarts, in mobile view

(Note: when source ordering doesn’t cut it, you can try AppendAround, by the web shop Filament Group. It can swap content pretty much anywhere when screen size changes.)

In closing

A common critique of frameworks like Foundation is that customization is hard. So far with the Cook Smarts redesign, we’ve found it easy, and the approaches above are complement the  solid base that the framework provides.

Next up, we’ll cover responsive images and video. Stay tuned! Subscribe by Twitter, RSS, or e-mail.