Making Mantle Deserialization Generic

The following discussion is geared towards Cocoa developers who have been using Mantle for some time. For those who haven’t, Mantle is a model framework for Cocoa and Cocoa Touch or, in simpler terms, is a framework that allows you to parse JSONs into objects and also serialize those objects back to JSON.

If you have been been working with Mantle, you’ve most likely been writing code like this:

...
[SomeNetworkingClass loadUserWithCompletion:^(NSURLResponse *response,
                                              id JSONObject,
                                              NSError *error) {
         if (!error) {
             NSError *mantleError;
             User* newUser = [MTLJSONAdapter modelOfClass:[User class]
                                       fromJSONDictionary:JSONObject
                                                    error:&mantleError];
            if (!mantleError) {
                //Do something with user
                ...
            } else {
              //Handle Mantle error
              ...
            }
         } else {
             //Handle network error
             ...
         }
     }];
 ...

You get the data from some service, test for errors (you check for errors right?), and finally use Mantle to parse the JSON (object or collection) to one of your model objects. This works great, but it tends to quickly create a lot of noise in the object responsible for this task.

At Prolific Interactive we’ve been experimenting with a generic block that we refer to as MantleBlock. The purpose of this block is to reuse the parsing code that we would otherwise be repeating all around.

Let’s do an overview of the method that generates the block:

+ (MantleBlock)jlm_parseBlockWithClass:(Class)className
                       firstCompletion:(void (^)(id items,
                                                 NSError* error))firstCompletion
                      secondCompletion:(void (^)(id items, 
                                                 NSError* error))secondCompletion
{

    NSParameterAssert(className);
    NSParameterAssert(firstCompletion || secondCompletion);
...

The returned MantleBlock is a typedef block to improve the readability: typedef void (^MantleBlock)(id, id, NSError*);. The important point here is that this method signature matches the one used in the callbacks of the backing object used to retrieve the data. In our case this is a AFHTTPSessionManager subclass with wrapped callbacks.

The method takes three parameters: a class object that must be a MTLModel subclass, since it will be used to determine the model object to parse the JSON response to, and two blocks with the same signature–firstCompletion and secondCompletion.

Finally, we assert the parameters, as this is standard practice on our code and this block is no exception.

MantleBlock newParseBlock = ^(id response, 
                              id responseObject, 
                              NSError* networkError) {
    if (networkError) {
        if (firstCompletion) {
            firstCompletion(nil, networkError);
        }

        if (secondCompletion) {
            secondCompletion(nil, networkError);
        }

        return;
    }

...

We now declare the MantleBlock that we’ll be returning. This block will be called by our AFHTTPSessionManager subclass and hence we have to check for a networkError. Then, if a firstCompletion block was provided we call it with a nil set of items and the networkError. We do the same for the secondCompletion block and then return. This example is what we’ll be doing for most of the rest of the block, as you’ll see.

...
        //The caller doesn't expect or doesn't want the response parsed that
        if (
            className == [NSNull class]) {
            if (firstCompletion) {
                firstCompletion(responseObject, nil);
            }

            if (secondCompletion) {
                secondCompletion(responseObject, nil);
            }

            return;
        }
...

This covers the case in which the caller doesn’t need or want the response object parsed.

...
NSAssert([responseObject isKindOfClass:[NSArray class]] ||
         [responseObject isKindOfClass:[NSDictionary class]],
         @"JSON objects are either Arrays or Dictionaries");
 ...

The assertion is pretty much self-explanatory.

...
NSError *mantleError = nil;
id parsedModelOfClass = nil;
if ([responseObject isKindOfClass:[NSArray class]]) {
    parsedModelOfClass = [MTLJSONAdapter modelsOfClass:className
                                         fromJSONArray:responseObject
                                                 error:&mantleError];
} else if ([responseObject isKindOfClass:[NSDictionary class]]) {
    parsedModelOfClass = [MTLJSONAdapter modelOfClass:className
                                   fromJSONDictionary:responseObject
                                                error:&mantleError];
}
...

Continuing from the assertion above, we parse the JSON object as a JSON Array or as JSON Dictionary. The goal is for the block to do the right thing without the caller providing that information.

...
        if (mantleError) {
            if (firstCompletion) {
                firstCompletion(nil, mantleError);
            }

            if (secondCompletion) {
                secondCompletion(nil, mantleError);
            }

            return;
        }
  ...

We do the callback dance again, but for any errors that happened during parsing.

        //No errors occurred. Call the dataStore block first if any.
        if (firstCompletion) {
            firstCompletion(parsedModelOfClass, nil);
        }

        if (secondCompletion) {
            secondCompletion(parsedModelOfClass, nil);
        }
    };

    return newParseBlock;
}

Everything went well if we reached this far in the block code so we do the callback dance once more time, but for the only success case and, finally, return the MantleBlock to the caller.

The code above was modified to simplify the discussion, but the complete version is here. Also, there’s a recording of a related lighting talk:

Also published on Jorge’s personal blog, http://jlmendezbonini.com

  • Jorge Luis Mendez

Sitting on the Dock of the Bay

I grew up in a small town in northeast Minnesota, and I just moved to one of the biggest cities in the country. This has been quite a journey and I’ve been asked to share it.

First off, I lived more like 10 miles outside of my small town. This would have been fine if I were a more outdoorsy, red-necked individual, but from a young age I enjoyed the more intellectual pursuits. My mom likes to tell a story of when I was young and I had done something naughty, her punishment was to send me to my room and take my toys away. But this had no effect on me since I would still have my books to read, and my poor mother was left in an ethical quandary, wondering whether it was acceptable to take a kid’s books away too.

I Left My Home in Minnesota

By the time I entered high school, I had already discovered the wonders of computers. My first exposure to programming was Game Maker and I quickly realized that the simple programming language it had was far more expressive than any GUI. In 11th grade, I signed up for the programming course as soon as it was announced , and I quickly outpaced the class when I decided to build a Tetris clone. For higher learning, I followed a friend to Fargo, ND and attained a degree in Computer Engineering. I definitely enjoyed learning about signal processing, VHDL, and simple processor architecture, but I eventually realized that type of work wasn’t for me.

Watchin’ the Trains Roll In

Thankfully, near the end of my sophomore year, I got a Samsung Captivate for Christmas and started delving into Android development. By summer break, I was the first employee of Myriad Devices (now Myriad Mobile) and developing Android apps for a variety of different clients. I also helped develop backends services and user experiences; the whole process of building something from the ground up fascinated me. For over three and a half years I called Myriad my home, but I never really felt like Fargo was the city for me.

Two Thousand Miles I Roam

The day after I arrived back from DroidconNYC, I received an email from a company looking for a senior Android developer. It was a breath of fresh air when I realized that the inquiry had not come through Linkedin and that they had actually researched what I had been doing at Myriad. So after a quick look at prolificinteractive.com, I agreed to a phone call that night. From that one phone call, I could tell Prolific knew what they were doing in mobile, had great culture, and could challenge me in new and different ways. After another phone interview or two, I began frantically planning a major life change.

Headed for the Frisco Bay

While planning a cross-country move, I was working remotely for a couple weeks; my start coincided with a kickoff of the project I’m currently on. I’m also helping lead the small Android team, more effectively now that I’m in the office. I’ve also volunteered to champion Android library creations at Prolific, so you’ll hopefully see some open source libraries in the near future and some blog posts to publicize them. And I’m certain there are other opportunities just on the horizon.

Watchin’ the Tide Roll Away

I’ve been in San Francisco for a few weeks now, and I’m really happy I moved here (and not just because 60º weather in November feels like paradise). This city is always doing something; my first weekend here I went to a Mac & Cheese Throwdown and had a marvelous lunch and met interesting people. I’m within walking distance of anything I could want, and Muni is just down the block. Compared to the rolling plains of North Dakota or the forests of Minnesota, looking out my window still leaves me with a sense of awe. I think I’ll stay here a while.

The Dock of the Bay – Otis Redding

  • Adam Koski

Artists don’t break rules – they follow them

I enrolled in quite a few art classes in college, and while I enjoyed them, I never entertained the idea that I could create a sensible career out of it. I wasn’t quite exotic, quite rebellious, quite hand-rolled cigarette enough to be a painter. I wasn’t someone to break all the rules, cry anarchy or pull-off painted jeans. I also didn’t like the notion of being poor, reaching the pinnacle of my career post-mortem (if ever), and cleaning paint brushes in a cramped, aging studio.

Fast forward. While I might not live the edgy lifestyle, I do find myself back in the general field: more specifically, as a product designer here at Prolific Interactive. If painted jeans and ciggies lay just outside my comfort zone, hipster flannels and oversized glasses do not. While I was most likely wrong about all artists being poor and living a life of bristle washing, I know I was wrong about one thing for certain.

Artists don’t break the rules, they follow them.

Cubism, impressionism, pop art, hyper realism; different sets of rules, followed strictly and developed to the extreme. Create all figures by applying harsh, abrupt lines. Apply paint to the canvas using layers of short brush strokes. Use a loud palette with bold styles.

Why are rules necessary? Paintings occupy a strange realm. They are a concrete, physical presence on the wall, but not truly “real”. You cannot reach through a painting and find yourself transported and yet, a convincing painting can make you feel as if you could. Rules create structure and this structure, even in abstract work, provides the viewer with a sense of realism, a pattern for the mind to comprehend. Every great work follows a set of rules. These rules evolve over a lifetime and taken collectively, become the style by which an artist is defined.

Likewise, mobile and web applications also occupy a quasi-state of reality. We can hold them in our hands and interact with them via touch, but they are not necessarily bound by the analog world and all the physics thus implied. As designers, we must take advantage of the ability for apps to transcend these laws, but also be extremely aware that these interactions can quickly deteriorate into a confusing mess if we are not creating a consistent, thoughtful experience. In other words, not adhering to a set of rules.

The more projects I complete as a product designer, the more I realize how applicable my art studio experience is to my job today. Erin, my art professor at the time, showed me that underneath even the most rebellious, most chaotic, free-spirited work, is a well-oiled machine of technique, craft and process. Whether creating paintings or developing products, these three virtues are necessary to construct a believable set of rules that make any work convincing.

1. Technique

Erin spent the majority of class walking in a slow circle, stopping by each of our stations to chat about our work.

When she reached my easel, she asked in a politely cloaked voice, “Are you trying to create a texture here?”

Me, realizing a trick question when I hear one, tried to give the ambiguous response of, “No?”

Erin proceeded to demonstrate the magic of a fan brush, feathering away any and all visible brush strokes. Per usual, I stood there entranced as she transformed my haggard yellow layer into a perfectly smooth surface. Handing back the brush, she told me, “It’s all about technique. Without it, the brush controls you, not the other way around.” When you learn new techniques, you control the end result rather than constantly adapting your painting to accommodate only what you already know how to do. It is hard to create a meticulously rendered figure if you don’t know how to properly mix skin tones. More importantly, proper technique provides an avenue for the artist to communicate with their audience. Without developing proper technique, the audience is left puzzling over discrepancies of color, light, texture, depth, etc. No longer believable, the painting falls flat.

While the number of new painting techniques and tools are endless, it wasn’t until recently that new design applications emerged to make our work as designers more efficient, more relevant and more adaptable. By learning new applications like Sketch, we can quickly build screens and leverage common elements such as symbols and styles. With new animation tools such as Pixate, we can now be more precise with our animations and better communicate complex interaction design to our engineers. With InVision, we can now create more lifelike prototypes for user testing in order to make our designs more adaptable. These programs help us communicate not only our designs, but also the decisions behind them. Rules are difficult enough to follow as one individual painting a canvas. These rules become even more difficult to manage when the process involves a team of 8-10 people, all contributing in varying capacities. The better our cross-functional communication, the more likely we will build a cohesive project that feels intentional to the user.

2. Craftsmanship.

I began painting the background solid phthalo blue, straight from the tube. Moments later, I found Erin, staring (and/or glaring) at me.

She darted over and asked, “You’re not really just squeezing that paint out of a tube and putting it straight onto your canvas, are you?”

I answered, somewhat sheepishly, “Not anymore.”

While technique refers to a developing a skill set, craftsmanship refers to an artist’s dedicated application of their skill set to the work even at the most detailed of levels. In the example above, Erin was fully aware that I knew how to properly mix paints to create any blue I needed (cool, warm, light, dark). I just needed a reminder that the small decisions matter as each color dictates the next, and eventually, a color palette emerges and dictates the mood of the painting. While one stray decision may not make much of an impact, a series of small decisions have a compounding effect, eventually dictating important factors like mood, atmosphere and tone. Craftsmanship separates good work from great. Every decision, every color, every brush stroke has to be intentionally crafted and refined or else the work feels unconsidered.

Currently working on an Android project, I have been referring to the Material Design guidelines released by Google, supporting their newest operating system, Android L. The guidelines delve into a level of detail not previously attempted in past releases, encouraging not only innovation, but also craft. For example, the guidelines provide an extensive grid system that takes into account keylines, metrics and baseline grids. This system ensures every component aligns to an 8 dip (density-independent pixel) grid and all text aligns to a 4 dip grid, thus establishing a consistent vertical rhythm. Though subtle, this rhythm provides the user with a predictable pattern, allowing the user to spend energy on more difficult tasks such as differentiating unique content. Current trends in product development encourage the release of an MVP in which sometimes, “worse is better“. While this mentality ensures products get off the ground and can be quickly tested and iterated, it can also become the crutch by which we leave the “nit-picky” details to a later date, if at all. Taking the time to craft these micro-level details from the get-go, pays dividends in the end, especially in an era of mobile and web design that demands a consistent, device-agnostic framework, where the decisions we make in a native mobile experience will inform the rules of the desktop experience.

3. Process

Every “large” canvas appears daunting. The white space overwhelms you and the faster you cover the canvas with a color–any color–the better.

Before I had time to mask away the white, Erin dropped a ream of copy paper on the drawing table, and told us to grab any brush larger than an inch. Erin explained, “Before anyone can begin, you need to complete 15 paint studies.” In my head I retorted, “Absolutely not.” It wouldn’t have surprised me if she turned around and gave a response, given that I always felt she had a way with mind reading. Try detailing complex lace patterns with a 1-in brush on a piece of copy paper. Not. Possible. However, working small forces you to consider issues relevant to the early development of the work, like composition and color. It also leaves you free to toss ideas into the trash. It’s hard to become protective and attached to a curling, brittle sheet of paper that required no more than 20 minutes to cover with paint.

Likewise, it’s hard to become attached to scribbles on a white board or crinkled copy paper. By imposing limitations on the medium (paper, pencils, or fat markers), the focus remains on the functionality or flow that you are trying to explore, not the “pretty”. Low fidelity mockups help (force) you to solve problems fast and early, leaving you free to kill your darlings. In fact, the greatest barrier to becoming a great designer is attachment. The more we understand design as a process rather than an outcome, the better the outcome becomes. The ability to detach allows you to explore not only more of your own ideas, but also incorporate ideas from others. And when producing a product that will be handled by thousands or even millions of different users, the more ideas the better. Moreover, with every idea we are able to explore, we are able to make more and more refined choices, better tailoring the experience to our user’s needs. Rules can be crafted in both the affirmative and negative; oftentimes it is just as important what you choose to rule out as it is what you choose to keep.

A place to follow all the rules

Just as it was important to find a mentor to teach me the basics of painting, during my recent job search, it was equally important to find an environment that would allow me to progress as a designer. While I have only been at Prolific a short while, I have already been able to refine my technique, craft and process in order to create more convincing, “rule-following” products. Understanding the innovative nature of the mobile industry, Prolific encourages people to learn the newest tools and techniques, including cutting-edge software such as Sketch, InVision and Pixate. Working within the agency model has also been rewarding as I have been able to refine my craft by diving into the more subtle, platform-specific details of mobile design. Finally, Prolific fosters a highly collaborative environment that encourages an iterative design process over static, premature deliverables.

If that doesn’t convince you, and it should, we also have an amazing office dog named Teddy. Witness the cuteness here.

  • Kelsea Everett

Converting Websites Into Mobile APIs

At Prolific, we often work with clients who want a mobile app, but don’t have an API. However, they do usually have a website. For several of these projects, we have turned to our in-house tool Glenlivet. Glenlivet is a framework that can convert any functioning HTML-based website into a JSON API and works with both static and dynamic websites. Glenlivet essentially provides a middleware that can convert all of the current functionality of a website into an API with the inputs and outputs of your choosing. This may not be a perfect solution, but it does solve the problem of a mobile API. It prevents the mobile client from having to do any dirty work, as they are simply consuming a clean API of your design which can be replaced later if necessary. Now, you are probably thinking that there must be something like this already. And you would be correct. Some examples of this are kimono, parsehub, and import.io, which are browser extensions, and scrapi which is a library that can be used in several languages. The browser extension solutions are full-on SAAS solutions with free and paid tiers with varying features. These appear to be great at pure data extraction, since they allow you to actually click around on the page you want to scrape and structure your response to your liking. Scrapi is similar in this respect in that it gives you the means to relatively easily extract data from a webpage. However, they all lack control for a full CRUD implementation of a website. Glenlivet provides a simple framework that allows the user to convert the entirety of a website’s functionality into an API.

How It Works

Glenlivet is a node framework (soon to be node module) that builds off of Express, request, and cheerio. Express provides a familiar way to manage the API’s structure. Request is used to actually make all of the http requests to the website that is being parsed. Cheerio allows for the scraping and converting of our html responses into clean consumable JSON. Endpoints are organized into objects called bottles which describe how a specific page on the website will be parsed and how it will be accessed through the API. Each bottle has an object that allows you to map your API request to the request you want to scrape on the website. This allows you to map restful API calls to any kind of format you may be scraping.

var ordersFilter = {
  "orders": function ($html, $) {
    return this.map('table.data-table tbody tr', {
      "id": function ($div) {
        return $div.find('a').attr('href').split('/')[7];
      },
      "displayNumber": function ($div) {
        return $div.find('td')[0].children[0].data;
      },
      "shippedTo": function ($div) {
        return $div.find('td')[2].children[0].data;
      },
      "orderDate": function ($div) {
        var date = $div.find('span.nobr')[0].children[0].data.split('/');
        if (date[0].length == 1) date[0] = '0' + date[0];
        if (date[1].length == 1) date[1] = '0' + date[1];
        if (date[2].length == 2) date[2] = '20' + date[2];
        return date[2] + '-' + date[1] + '-' + date[0];
      },
      "status": function ($div) {
        return $div.find('em').html();
      },
      "total": function ($div) {
        return parseFloat($div.find('span.price').html().replace(/$/, ''));
      }
    });
  }
};

As seen in the code above, each bottle can be assigned an object which describes how it will scrape its target page and how to format that information into a JSON response. These objects reflect the format of the desired JSON response with each property having a function returning the value to populate it. These functions can contain any logic within them, allowing them to combine information from multiple parts of the page or compute things like totals. Each bottle can also have middlewares attached to it. There are several types of middleware, and the two most commonly used are request and response middleware. Request middleware are executed prior to the bottle making a request to the website and response middleware are executed after the response from the website is received. Glenlivet comes with middleware for handling caching, session management, and many other things. It is also very easy to write your own in case you need to scrape multiple pages for a request, or create a complicated request to scrape a certain page.

Tougher Problems It Solves

Session Management:. One of the biggest problems Glenlivet solves is session management. Like I mentioned earlier, Glenlivet comes out of the box with a middleware to manage sessions. As long as you have redis enabled (or some other kind of cache), this middleware can be used to track and store all of the cookies related to a single session. This allows you to easily take advantage of session-dependent site functionality through your API. Things like logging in and tracking a non-registered user’s cart become easy. As long as a session token is passed in as part of the request, that request will have all of the previously-saved cookie information sent with it.

Caching: Another middleware that comes out of the box is caching. This middleware allows you to determine how long a bottle should be cached for and allows you to maximize the speed of your API whenever caching is possible with little effort.

How We Have Used It At Prolific

Initially, we thought of Glenlivet as a tool to provide a stand-in API while a “real” API was being developed, or to be used in prototyping. We were surprised when we saw how reliably and quickly it performed, and now the tool has become a legitimate solution for production APIs. Glenlivet allows us to leverage websites to quickly build a clean API that can be consumed by any mobile device, giving us the ability to deliver a quality product within a small time frame.

Caveats

Parsing websites into APIs has its drawbacks, of course.

  1. If the site goes down, so does your API.
  2. Changes made to structure of the website can break a part of the API, which can be mitigated with automated testing against a staging environment.
  3. Your API’s performance will be tied to your website’s, which can be mitigating with caching.
  4. It is sometimes difficult to add functionality to the API that does not exist directly on the site, which may involve making multiple calls behind the scenes. Performance can take a hit, or it may require some kind of crazy caching scheme on the client or API to maintain state.

All in all, Glenlivet has developed into a useful tool. If you are willing to deal with the limitations, it can help you get your product out the door much faster. We have found that the benefits of speed and reduced cost have proven this method to be an effective way to launch a mobile API.

  • Conor Dawson

Adapting to Agency

When Prolific reached out to me about leading a product team in their San Francisco office, I had never considered working for an agency. After college, I jumped straight from my engineering program into an ecommerce startup based in San Diego. Moving back to the Bay Area, where I grew up, it was my intention to stay in startups, diving further into the community that defines the tech scene here.

Curiosity, more than anything else, motivated me to take the interview. Arriving at the office, it was hard to ignore the pleasant atmosphere, the light streaming through the large windows and the casual camaraderie as everyone sat down to lunch at the office’s picnic table. Talking through my experiences and the expectations of the role with Pat and Joe, I was surprised to discover how compatible my startup experience was with the innovative atmosphere of a digital agency.

It’s been six weeks since I joined Prolific as a Product Manager and I could not be happier with my decision.

Building from the ground up

One of the most exciting challenges I can face as a PM is starting from scratch on a new product; at Prolific, I get to do that on every project. It’s both invigorating and a little frightening to scope and plan an entire app, but it also means that I get to learn how to do things right the first time. I am free to experiment with new work styles and organizational flows to determine the process that works best for me and for my team. Most importantly, the open culture here makes it easy to learn from every failure and success, both others’ and my own.

Everyone is client-facing

I am expected to understand my client, their industry, and the business challenges they face to make sure the product we deliver meets all of their goals. While Prolific has account managers for every project, all phases of our work are open to the client and almost every meeting includes stakeholders from their internal team. While this presence means we are always aligned with our client’s needs, it also requires me to maintain a constant dialogue around the decisions we make and the reasons by which we make them. Further, while team dynamics are important to every project, the openness of our work necessitates an extra degree of closeness between product, design, and engineering. The alignment between these core product areas not only improves the quality of our overall work, but drives us to become stronger contributors and communicators individually as well.

Always innovating

When working in-house, I would never have the time or resources to implement every new trend or technology that comes along; at Prolific, that is exactly what our clients hire us to do. We are constantly looking for better workflows and tools to improve our work process. The freedom to experiment with both tools and processes keeps me from getting fixated on a single approach. I see the value in being able to adapt to each new technology, especially as the pace of development in mobile product seems to get ever faster. Further, we are required to become subject matter experts in the tools we use, often onboarding client engineers and designers to use our process even after our scope of work is completed. From team dynamics to planning tools, I’ve learned a lot in my short time at Prolific, but, more importantly, I’m excited for all of the lessons to come.

  • Chelsea Fischbach