One of the hardest things a programmer has to do on a daily basis is naming things. Anything that we name will stay with us for a while and it's very likely that other programmers will have to use the thing we just named as well. So naming something properly is very important. It's often said that the two hardest problems in programming are naming things and cache invalidation. I tend to agree with that statement.

A lot of times when I struggled with a piece of code, naming could have made my struggle easier. A function name like fetchData might make sense at the time of writing. But a few weeks later you look at that code and you start wondering.. what data does that function fetch, exactly? Couldn't it have been named fetch just as well? I mean, the fact that it fetches data is implied. Or is it? Almost always there's room for discussion on the naming of things in code. However, that's not the point I want to make in this post. This post is about naming things in the context of tutorials and books. In other words, code snippets that have a teaching purpose.

When you write code that is intended or teaching you should make sure that you keep two things in mind.

1. You want to get a certain point or concept across to the reader. The code should make this point as clear as possible.
2. You want to stick to best practices so you're not teaching bad habits.

I have found that these two goals can easily be in conflict.

An example

Let me show you an example I have found in the Functional Swift book by the folks over at objc.io.

struct Times<T, U> {
    let fst: T
    let snd: U
}

These four lines won't look very scary to somebody who is familiar with Generics in Swift. They will know that T and U are just placeholders for types. Any value could go there, we could have defined them as A and B or Hello and World just as well. However, the best practice is that generic naming starts at T and seems to work it's way up through the alphabet from there. So that's why this snippet uses the T and U as type names for the generic portion of this struct. For beginners this might be confusing so you could argue that more descriptive type names would be better. For example, FirstType and SecondType are a lot clearer. They don't follow best practices though, so picking between the two can prove to be quite tough and in my opinion it depends on the point you're trying to get across. In the above snippet the concept of generics is already explained in previous chapters, so T and U are just fine in this snippet. If this snippet was about explaining generics it might have been better to help the reader out a little bit by breaking best practices for the sake of readability and introducing the proper way after explaining how generics work.

What does bother me about the way the Times struct is defined is the way fst and snd are named. The author chose to sacrifice readability in order to save a few keystrokes. In production code this happens all the the time. Loops like for u in users or [obj.name for obj in res] are not uncommon in Swift and Python. One might even argue that using short names like this is actually some sort of convention and while that might be true, if you're explaining something in code you do not want the reader to have a single doubt about what something does because of the name. For example, fst and snd in the Times struct could have been named first and second or left and right. A loop like for u in users could be for user in users. [obj.name for obj in res] could be clarified by writing [user.name for user in fetched_users]. These more verbose versions of code might not be fully in line with best practices or common in production code, but when you're using code to explain something you need to make sure that your code is as readable as possible.

In conclusion

Naming things is hard, there's no doubt about it. What might be clear one day could look like gibberish the next. What might be obvious to me could be nonsense to you. Conventions help ease the pain. If everybody uses the same rules for naming things it becomes a little bit easier for programmers to come up with good naming. However, we should not forget that people who read our code to learn more about a certain topic might not be fully aware of certain conventions. Or they might not be very good at understanding what i, j and k mean when we're nesting loops. And let's be honest, those single letter variables lack all kinds of meaning. Even though it's convention and we all do it, it's just not a good convention follow when teaching. At least not all of the time.

Next time you write code that's intended for explaining something, ask yourself if breaking a convention will make your snippet simpler or easier to follow. If the answer is yes, it just might be a good idea to break the convention and save your readers some brainpower.

For a long time web developers have been complaining about the lack of updates (and modern features / APIs) for Safari. With the current release cycle for Safari we get a major updated version with every major OS release (which only happens once a year). This release cycle, and the lack of new features in Safari made some people go as far as calling Safari the new IE.

NowApple has launched Safari Technology Preview. Developers can use this browser to try out new web features way before they land in the consumer version of Safari. The developer version is based off the WebKit Nightly Builds and will contain the latest and greatest features that were added to the WebKit platform. According to the The Next Web Apple will be updating the Technology Preview version of their browser approximately every two weeks, which is a lot more than they are updating the main browser.

When comparing this browser with the Chrome Canary we should consider Canary as more of a playground, features are going to change a lot before making it to the Chrome browser or could disappear completely. The Safari Technology Preview is intended as a browser that provides people with features that are intended to be shipped (and are mostly ready for production).

So why is this great news?

In the title of this post I mentioned that I think the Safari Technology Preview is great news. The reason I consider this great news is that if Apple sticks to their plan and updates this Preview every two weeks, it might be a sign that Apple intends to ship more updates for the main Safari browser as well. The Technology Preview might just be Apple's way of experimenting with a faster release cycle for their consumer product. Also, if developers start developing for the Preview platform they are testing new features out in the wild, which just might give Apple the confidence to release new features to end-users more rapidly once they now a certain feature work well in real life.

All in all I really like this move from Apple and it might make Safari a more solid, robust, modern and up-to-date browser than it is today.

Recently I released my first personal iOS app into the wild. The app is called unit guide for Starcraft 2 and it provides Starcraft 2 player with up to date and accurate information for every unit in the game. Instead of manually creating a huge JSON file I wrote a web scraper in node.js that allows me to quickly extract all the data I need and output it in a JSON format. In this post I will explain how you can build something similar using techniques that are familiar for most web developers.

Step 1: preparing

Before you get started you're going to want to install some dependencies. The ones I have used are: request, cheerio and promise. Installing them will work like this:

npm install --save request cheerio promise

If you don't have npm installed yet then follow the instructions here to install node and npm.

Once you have all the dependencies, you're going to need a webpage that you will scrape. I picked the Starcraft 2 units overview page as a starting point. You can pick any page you want, as long as it contains some data that you want to extract into a JSON file.

Step 2: loading the webpage

In order to start scraping the page, we're going to need to load it up. We'll be using request for this. Note that this will simply pull down the html, for my use case that was enough but if you need the webpage to execute javascript in order to get the content you need you might want to have a look at phantomjs. It's a headless browser that will allow javascript execution. I won't go in to this right now as I didn't need it for my project.

Downloading the html using request is pretty straightforward, here's how you can load a webpage:

var request = require('request');

request('http://eu.battle.net/sc2/en/game/unit/', function(error, result, html){
    if(error) {
        console.log('An error occurred');
        console.log(error);
        return;
    }

    console.log(html);
});

Getting the html was pretty easy right? Now that we have the html we can use cheerio to convert the html string in to a DOM-like object that we can query with css style selectors. All we have to do is include cheerio in our script and use it like this:

var request = require('request');
var cheerio = require('cheerio');

request('http://eu.battle.net/sc2/en/game/unit/', function(error, result, html){
    if(error) {
        console.log('An error occurred');
        console.log(error);
        return;
    }

    var $ = cheerio.load(html);
});

That's it. We now have an object that we can query for data pretty easily.

Step 3: finding and extracting some content

Now that we have the entire webpage loaded up and we can query it, it's time to look for content. Or in my case, I was looking for references to pages that contain the actual content I wanted to extract. The easiest way to find out what you should query the DOM for is to use the "inspect element" feature of your browser. It will give you an overview of all of the html elements on the page and where they are in the page's hierarchy. Here's part of the hierarchy I was interested in:

You can see an element that has the class table-lotv in the hierarchy. This element has three children with the class unit-datatable. The contents of this unit-datatable are of interest for me because somewhere in there I can find the names of the units I want to extract. To access these data tables and extract the relevant names you could use a query selector like this:

$('.table-lotv .unit-datatable').each(function(i, dataTable){
    var race = $(dataTable).find('.title-bar span').text();
    var $unitnames =  $(dataTable).find('.databox table .button-rollover');
});

In the above snippet $('.table-lotv .unit-datatable') selects all of the data tables. When I loop over these I have access to the individual dataTable objects. Inside of these objects I have found the race name (Terran, Protoss or Zerg) which is contained inside of a span element which is contained in an element with the class title-bar. Extracting the name isn't enough for my use case though. I also want to scrape each unit's page and after doing that I want to write all of the data to a JSON file at once. To do this I used promises. This is a great fit because I can easily create an array of promise objects and wait for all of them to be fulfilled. Let's see how that's done, shall we?

Step 4: build your list of promises

While we're looping over the dataTable objects we can create some promises that will need to be fulfilled before we output the big JSON file we're aiming for. Let's look at some code:

var request = require('request');
var cheerio = require('cheerio');
var Promise = require('promise');
var fs = require('fs');

request('http://eu.battle.net/sc2/en/game/unit/', function(error, result, html){
    //error handling code and cheerio loading

    var promises = [];

    $('.table-lotv .unit-datatable').each(function(i, dataTable){
        var race = $(dataTable).find('.title-bar span').text();
        var $unitnames =  $(dataTable).find('.databox table .button-rollover');

        promises.append(scrapeUnits($unitnames));
    });

    Promise.all(promises).then(function(promiseResults){
        var data = {};

        // use the promiseResults to populate and  build your data object...

        // write the JSON file to disk
        fs.writeFile('public/units.json', JSON.stringify(data), function(err){
            if(err) { console.log(err); }
        });
    });
});

Okay, so in this snippet I included Promise to the requirements. Inside of the request callback I created an empty array of promises. When Looping over the data tables I insert a new promise which is returned by the scrapeUnits function (I'll get to that function in the next snippet). After looping through all of the data tables I use the Promise.all function to wait until all promises in my promises array are fulfilled. When they are fulfilled I use the results of these promises to populate a data object (which is our JSON data). The function we provide to the then handler for Promise.all receives one argument. This argument is an array of results for the responses we put in the promises array. If the promises array contains three elements, then so will the promiseResults. Finally I write the data to disk using fs. Which is also added in the requirements section. (fs is part of node.js so you don't have to install that through npm).

Step 5: nesting promises is cool

In the previous snippet I showed you this line of code:

promises.append(scrapeUnits($unitnames));

The function scrapeUnits is a function which returns a promise, let's have a look at how this works, shall we?.

function scrapeUnits(unitUrls) {
    return new Promise(function(fulfil, reject) {
        var units = [];

        // some code that loads a new page with request
        // some code that uses querySelectors and cheerio to extract data
        // some code that creates a unit object and eventually adds units to the array

        // eventually we're done with grabbing data for our units and we do this:        
        fulfil(units);
    });
}

This function is pretty straightforward. It returns a new Promise object. A Promise object takes one function as a parameter. The function should take two arguments, fulfil and reject. The two arguments are functions and we should call them to either fulfil the Promise when our operation was successful, or we reject it if we encountered an error. When we call fulfil, the Promise is "done". When we use Promise.all, the then handler will only get called if all promises passed to all have been fulfilled.

Step6: Putting it all together

var request = require('request');
var cheerio = require('cheerio');
var Promise = require('promise');
var fs = require('fs');

request('http://eu.battle.net/sc2/en/game/unit/', function(error, result, html){
    if(error) {
        console.log('An error occurred');
        console.log(error);
        return;
    }

    var $ = cheerio.load(html);

    var promises = [];

    $('.table-lotv .unit-datatable').each(function(i, dataTable){
        var race = $(dataTable).find('.title-bar span').text();
        var $unitnames =  $(dataTable).find('.databox table .button-rollover');

        promises.append(scrapeUnits($unitnames));
    });

    Promise.all(promises).then(function(promiseResults){
        var data = {};

        // use the promiseResults to populate and  build your data object...

        // write the JSON file to disk
        fs.writeFile('public/units.json', JSON.stringify(data), function(err){
            if(err) { console.log(err); }
        });
    });
});

function scrapeUnits(unitUrls) {
    return new Promise(function(fulfil, reject) {
        var units = [];

        // some code that loads a new page with request
        // some code that uses querySelectors and cheerio to extract data
        // some code that creates a unit object and eventually adds units to the array

        // eventually we're done with grabbing data for our units and we do this:        
        fulfil(units);
    });
}

The above script is a stripped version of the code I wrote to scrape all of the unit information I needed. What you should take away from all this, is that it's not very complex to build a scraper in node.js. Especially if you're using promises. At first promises might seem a bit weird, but if you get used to them you'll realise that they are the perfect way to write maintainable and understandable asynchronous code. Especially Promise.all is a very fitting tool for what we're trying to do when we scrape multiple webpages that should be merged into a single JSON file. The nice thing about node.js is that it's javascript so we can use a lot us the technology we also use in a browser. Such as the css / jQuery selectors that cheerio makes available to us.

Before you scrape a webpage, please remember that not every webpage owner appreciates it if you scrape their page to use their content so make sure to only scrape what you need, when you need it. Especially if you start hitting somebody's websites with hundreds of requests you should be asking yourself if scraping this site is the correct thing to do.

If you have questions about this article, or would like to learn more about how I used the above techniques, you can let me know on Twitter

Update for Xcode 11:
Unfortunately, it appears that this method of cleaning derived data no longer works😕. Looks like we're stuck purging ~/Library/Developer/Xcode/DerivedData/ by hand again. If you do know of a workaround similar to the one described here, send me a tweet and I'll update this post!

Any iOS developer that has spent significant time with Xcode is familiar with at least a couple of it's caveats. Random crashes, slowness, autocomplete not working for a few seconds and build errors right after you've added or removed a library. Or, just a random appearance of 200+ warnings like I had just now. The solution for quite a few problems with Xcode's building process can be found in clearing out your derived data. In the past I would always fire up a new terminal window, type in something like open ~/Library/Developer/Xcode/DerivedData/ and then manually clearing out the folders I think aren't needed. But today I found out that Xcode has a built in fix-me button, right in your project organizer!

All you have to do is go to the project organizer (window -> projects) click the button that's outlined and you're done. Any issues with your derived data should be cleaned up (for now) and your Xcode should stop complaining about silly things for a while now.

Happy coding!

A little while ago I wrote a post about PromiseKit. In this post I wrote mainly about how you could wrap API calls in Promises using the NSURLConnection extension that the creator of PromiseKit provides. Since writing that article I've had a bunch of people asking me more about PromiseKit. More specifically, some people wanted to know how they could wrap their existing code in Promises. To illustrate this I'm going to use Parse as an example.

A regular save action in Parse

Before we start making Promises, let's have a look at how you'd normally do something with Parse. An example that any Parse user probably has seen before is one where we save a PFUser.

let user = PFUser()
user.email = email
user.password = password
user.username = email

user.signUpInBackgroundWithBlock {(succeeded: Bool, error: NSError?) -> Void in
    guard error == nil else {
        // handle the error
    }

    // handle the succesful save
}

Above code should be fairly straightfowards. First we create a user, then we call signUpInBackgroundWithBlock and then we specify the block that should be executed after the user has been signed up. A lot of Parse's save and fetch actions follow this pattern where you use callbacks as a means to handle success and error cases. In my previous post I explained that Promises are a cleaner method to deal with asynchronous operations, but wrapping something like signUpInBackgroundWithBlock in a Promise isn't very straightforward.

Creating a custom Promise

Setting up a Promise isn't very hard. What you're going to need to decide on in advance is what your Promise is going to return. After that you're going to need to figure out the conditions for a fulfilled Promise, and the conditions for a rejected Promise. How about a simple example?

func doSomething(willSucceed: Bool) -> Promise {
    return Promise { fulfill, reject in
        if(willSucceed) {
            fulfill("Hello world")
        } else {
            reject(NSError(domain: "Custom Domain", code: 0, userInfo: nil))
        }
    }
}

The function above returns a Promise for a String. When you create a Promise you get a fulfill and reject object. When you create your own Promise it's your responsibility to make sure that you call those objects when appropriate. The doSomething function receives a Bool this flags if the Promise in this example will succeed. In reality this should be dependent on if the action you're trying to perform succeeds. I'll show this in an example a little bit later. If we want this Promise to succeed we call fulfill and pass it a String because that's what our Promise is supposed to return when it's succesful. When the Promise should be rejected we call the reject function and pass it an ErrorType object. In this example I chose to create an NSError.

Now that we have explored a very basic, but not useful example, let's move on to actually wrapping a Parse call in a Promise.

Combining Parse and PromiseKit

When you're doing asynchronous operations in Parse you call functions like 'signUpUserInBackgroundWithBlock'. This function takes a callback that will be executed when the user has signed up for your service. Let's see how we can transform this callback oriented approach to a Promise oriented one.

func signUpUser(withName name: String, email: String, password: String) -> Promise {
    let user = PFUser()
    user.email = email
    user.password = password
    user.username = name

    return Promise { fulfill, reject in
        user.signUpInBackgroundWithBlock { (succeeded: Bool, error: NSError?) -> Void in
            guard error == nil else {
                reject(error)
                return
            }

            fulfill(succeeded)
        }
    }
}

In the example above a function is defined signUpUser, it takes some parameters that are used to set up a PFUser object and it returns a Promise. The next few lines set up the PFUser and then we create (and return) the Promise object. Inside of the Promise's body we call signUpInBackgroundWithBlock on the PFUser. The callback for this function isn't entirely avoidable because it's just how Parse works. So what we can do, is just use the callback to either call reject if there's an error or call fulfill when the operation succeeded.

That's all there is to it, not too complex right? It's basically wrapping the callback inside of a Promise and calling reject or fulfill based on the result of your Parse request. One last snippet to demonstrate how to use this new function? Sure, let's do it!

signUpUser(withName: "Donny", email: "[email protected]", password: "secret").then { succeeded in
    // promise was fulfilled! :D
}.error { error in
    // promise was rejected.. :(
}

The way this works is basically identical to how I described in my previous post. You call the function that returns a Promsie and use the then and error (report in an earlier PromiseKit release) to handle the results of the Promise.

Wrapping up

In this post I've showed you how to take something that takes a callback and wrap it in such a way that it becomes compatible with PromiseKit. The example was about Parse but this principle should apply to just about anything with a callback.

The only thing I didn't cover is where to actually implement this. I did that on purpose because it really depends on your architecture and partially on preference. You could opt to put the wrapping functions in a ViewModel. Or you could create some kind of Singleton mediator. Or maybe, and I think I prefer this method, you could write some extensions on the original objects to provide them with functions like saveUserInBackgroundWithPromise so you can actually call that function on a PFUser instance.

If you'd like to know more, have questions or have feedback, you can find me on Twitter or in the (amazing) iOS Developers Slack community.

It's no secret that nginx has certain advantages over apache. One of them is that nginx is supposed to have better options for forwarding requests to ports other than port 80. My VPS has been using apache ever since I set it up because at the time apache was the only server I knew how to install and set up. But, as I learned more and wanted to start using different ports for node.js or python apps, I figured that I needed to move over to nginx. And so I did. In this post I will describe how.

Preparing

When I started the process of migrating I made sure that I had a backup of my most important website files. Not that I expected my files to blow up somehow, I just wanted to make sure that I wouldn't lose anything. Fortunately I have most of my projects in gitlab so that wasn't really an issue. After that I downloaded a back-up of my blog's database. Again, just to be sure.

After I reassured my paranoid mind that everything would be fine I went on to install the things I needed to start migrating. There were only two things I really needed, nginx and php5-fpm. The nginx package is needed to launch the nginx server and php5-fpm is what nginx will hand php files off to. Installing them took just two simple commands.

sudo apt-get install nginx
sudo apt-get install php5-fpm

Configuration

Before I was able to make nginx serve my websites I had to configure php5-fpm so it doesn't serve files based on a best guess, but only if we have an explicit (valid) file path. Even though this sounds like something that would make a great default I had to set that myself. In order to make this happen I had to modify the /etc/php5/fpm/php.ini file. This is the line that I had to change:

cgi.fix_pathinfo=0

If the line is set like that it's good. That's the secure config we're looking for. Next I had to set up the socket that php-fpm and nginx will use to communicate. The configuration for that is in /etc/php5/fpm/pool.d/www.conf and the line where the listening is configured should look like this.

listen = /var/run/php5-fpm.sock

Once this is set, php-fpm need to be restarted for the changes to take effect.

sudo service php5-fpm restart

Setting up nginx

After setting up php-fpm it was time to start setting up my websites. Just like apache, nginx can have multiple websites configured. Translating a basic website is not very hard, it took me something like 30 minutes to figure out how I could move Arto from an apache to an nginx config. A virtual host in apache might look something like below.

<VirtualHost *:80>
    ServerAdmin webmaster@localhost
    ServerAlias www.artoapp.nl
    ServerAlias artoapp.nl  

    DocumentRoot /var/www/www.artoapp.nl
    <Directory />
        Options FollowSymLinks
        AllowOverride all
    </Directory>
    <Directory /var/www/www.artoapp.nl/>
        Options Indexes FollowSymLinks MultiViews
        AllowOverride all
        Order allow,deny
        allow from all
    </Directory>

    ScriptAlias /cgi-bin/ /usr/lib/cgi-bin/
    <Directory "/usr/lib/cgi-bin">
        AllowOverride None
        Options +ExecCGI -MultiViews +SymLinksIfOwnerMatch
        Order allow,deny
        Allow from all
    </Directory>

    ErrorLog ${APACHE_LOG_DIR}/error.log

    # Possible values include: debug, info, notice, warn, error, crit,
    # alert, emerg.
    LogLevel warn

    CustomLog ${APACHE_LOG_DIR}/access.log combined
</VirtualHost>

Translating this to an nginx configuration looks like the following snippet.

server {
    listen 80;

    root /path/to/www.artoapp.nl;
    server_name artoapp.nl www.artoapp.nl;
    index index.html;

    location / {
        try_files $uri /index.html;
    }

    location /api/ {
        try_files $uri /api/index.php;
    }

    location /cms/ {
        try_files $uri /cms/index.php;
    }

    location ~ \.php$ {
        fastcgi_split_path_info ^(.+\.php)(/.+)$;
        fastcgi_pass unix:/var/run/php5-fpm.sock;
        fastcgi_index /index.php;
        include fastcgi_params;
    }

    location = /robots.txt {
        allow all;
        log_not_found off;
        access_log off;
    }

    location ~ /\. {
        deny all;
    }

    location ~* /(?:uploads|files)/.*\.php$ {
    deny all;
    }
}

What you might notice here is that the nginx configuration is a little bit longer and more detailed than the one for apache. This is because apache uses .htaccess files to set up global or per folder access and rewrite rules. Nginx doesn't use these files and instead the configuration for that goes into your server configuration.

The first part tells nginx on which port it should listen. This makes it easy to spawn servers on different ports. Or to have multiple domains on a single port. The next three lines tell nginx what the full path to the website is, what server name it should use and which file should be used as the index. The first two properties can also be found in the site configuration for apache. The last one, index is not in the apache config. It tells nginx which file is the index file for the website.

Next up:

location / {
    try_files $uri /index.html;
}

location /api/ {
    try_files $uri /api/index.php;
}

location /cms/ {
    try_files $uri /cms/index.php;
}

This section is similar to what the .htaccess would do. It tells nginx how it should attempt to serve files for certain paths. So if we're at /, it tries to serve the requested files. If that's not possible, we get index.html. If we request something from /api/ it tries to serve the requested path as a file, if that fails we get sent through to index.php file. The /cms/ section works just like the /api/ section, just a different path.

The part after that are intended to send files through to php-fpm if the requested file is a php file. Next there's a special declaration for robots.txt. Finally we deny access to all files that start with . because those files are not supposed to be accessed and the final block denies execution of php in the uploads and files folder.

Making the switch

After translating Arto I had to convert a bunch of other websites with very similar configurations. When I was done with that it was time to make the switch. All it took to migrate after setting up my configuration was to stop apache (sudo service apache2 stop) and start nginx (sudo service nginx start or sudo service nginx restart if nginx was already running for some reason).

I expected things to break, fall over and not work because migrating just couldn't be this easy. But, in fact, it was. I only had one issue with a php extension I use, it wasn't enabled on php-fpm yet. Enabling it was all it took to get everything up and running. Next up, building awesome node.js and python websites instead of using php! If you're looking for a more complete guide of what you can do with nginx, they have great docs over at nginx.org.

If you have questions about this article or if you've got feedback for me, you're always welcome to shoot me a tweet.

Some of the most engaging apps we use today are apps that require network connectivity of some kind. They communicate with an API somewhere to fetch and store data for example. Or they use an API to search through a huge amount of data. The point is, you don't want your application to sit around and wait while an API call is happening. The same is true for a computing task that's heavy, for example resizing an image or storing it to disk. You want your UI to be snappy and fast. In other words, you don't want to do your heavy lifting on the main (UI) thread of a device.

Taking something off of the main thread

There's several ways to take something away from the main thread. An NSURLConnection automatically performs requests in the background and uses delegates to make callbacks about progress or completion for example. You can also use the dispatch_async function to make something happen on a different thread. While this works perfectly fine it's not very ideal. When an NSURLConnection performs it's delegate callbacks it has to be coupled to that delegate. Also, imagine you want to chain together a couple of network requests; it will start to become kind of messy to keep track of everything.

Now imagine an object that you can pass around, it will automatically perform a task once it's done what it's supposed to do. These tasks can be chained so if you want to chain multiple things together it's very simple. Or maybe you want your callback to fire only if a couple of tasks are complete. Imagine implementing that with multiple NSURLConnections. You would probably have multiple instances and whenever one is complete you check the status of the others and then when all are complete you can actually execute the code you've been meaning to execute. That sounds a lot more complicated than just writing:

wait(request1, request2, request3).then { (result1: NSData, result2: NSData, result3: NSData) in }

The above snippet is actually really close to how PromiseKit works. Let's explore that a bit further, shall we?

Note: I am going to apply PromiseKit to network requests for this post. The concepts actually apply to anything that you want to do asynchronously.

A simple Promise example

To demonstrate a simple Promise we'll make a network request. First we create an NSURLRequest that we'll pass to an NSURLConnection. Then we kick off the loading with a Promise so we can use the result once the request is done:

var req =  NSURLRequest(URL: NSURL(string: "http://example.com/api/feed/")!))
NSURLConnection.promise(req).then{ (data: NSDictionary) in
  // use the data we just received
}

PromiseKit has provided us with an extension on NSURLConnection that allows us to call promise(req:NSURLRequest) on it. After that we call then. The code that's inside of this closure gets called once the Promise is fulfilled. This happens whenever the request completed with success. If the request fails we can add a report ('catch' in swift 1.2) as well to make sure we catch that error:

var req =  NSURLRequest(URL: NSURL(string: "http://example.com/api/feed/")!))
NSURLConnection.promise(req).then{(data: NSDictionary) in
  // use the data we just received
}.report{ error in
  // do something with the error
}

And if there's code we want to execute regardless of error or success we can use ensure (defer in swift 1.2) like this:

var req =  NSURLRequest(URL: NSURL(string: "http://example.com/api/feed/")!))
NSURLConnection.promise(req).then{ (data: NSDictionary) in
  // use the data we just received
}.report{ error in
  // do something with the error
}.ensure{
  // perform action regardless of result
}

If you understand this, you basically understand all you need to know to start using Promises in a very basic way. But let's get a little bit more advanced and start returning our own Promise objects.

Returning Promises

Imagine this, we're building an application that uses an API. We want to ask the API for a user's feed and we want to use PromiseKit for this. A nice implementation might be to have an API instance that has a method on it called fetchUserFeed. That method will return a Promise so we can easily use the result from the API in the class that actually wants the API to fetch data, a ViewModel for example. The fetchUserFeed function might look something like this:

func fetchUserFeed() -> Promise<Feed>
  var req =  NSURLRequest(URL: NSURL(string: "http://example.com/api/feed/")!))
  return NSURLConnection.promise(req).then{(data: NSDictionary) -> Feed in
    return Feed(dataDict: data)
  }
}

Note: Feed is a just a data object not included in the sample for brevity. It is used to illustrate how you would return something from a Promise

The function above is very similar to what we had before except now it returns NSURLConnection.promise which is a Promise. The then of that Promise now returns a Feed and the fetchUserFeed function now returns Promise<Feed>. What this means is that fetchUserFeed now returns a Promise that will resolve with a Feed. So if we use this function it looks like this:

let api = DWApi()
api.fetchUserFeed().then{ feed in 
  // use the feed
}

That's pretty clean, right? Now let's say that we not only want to fetch the Feed but also a user's Profile. And we want to wait until both of these requests are done (and successful). We can use the when function for that:

let api = DWApi()
when(api.fetchUserFeed(), api.fetchUserInfo()).then {feed, info in 
  // both requests succeeded, time to use the feed and info
}.report { error in
  // one or both of the requests have failed
}

Let's make this this a little bit more complicated shall we? Currently we're able to use an API to fetch stuff, and we're able to do multiple requests and wait until they're all complete. Now we're going to wrap that into a function we can call from somewhere else. The function will return a single object that uses both a Feed and UserInfo to create itself. Let's call it ProfileModel.

func fetchProfileModel() -> Promise<ProfileModel> {
  let api = DWApi()
  return when(api.fetchUserFeed(), api.fetchUserInfo()).then {(feed: Feed, info: UserInfo) -> ProfileModel in 
    return ProfileModel(feed: feed, info: info)
  }
}

And when we want to use this function we would write something like this:

let viewModel = DWViewModel()
viewModel.fetchProfileModel().then{ profileModel in 
  // use profile model
}.report { error in
  // handle errors
}

That's pretty cool isn't it? Pretty complicated logic wrapped in promises to make it simple and enjoyable again.

Wrapping it up

In this post we've touched up on the basics of PromiseKit, a library that makes asynchronous programming cleaner and easier. I've shown you how to use them in a very simple and basic setting and in a situation where you wait for multiple operations/promises and return a single promise with both results. Promises can help you to build a very clean API for your async operations and they help you to keep your code clean and readable. I highly suggest to try using promises in your own projects, they're really cool and easy to use. To find out more about PromiseKit you should check out their github.

If you have questions or feedback for me on this subject make sure to hit me up on Twitter or look for me in the ios-developers slack community.

Whenever I'm programming, I have a goal in mind, generally a problem to solve. I want my solutions to be simple, yet elegant and reliable. Thankfully, Swift is a great language for this. The language is safe, its syntax is beautiful with great readability. The way Swift handles nullability with Optional contributes greatly to its safety. Can you imagine having a language where you don't know whether something could be nil? Well... languages like Objective-C and Java required developers to constantly check for null or nil values to prevent crashes.

I'm sure you can imagine that this would go wrong all the time and if you Google for a term like null pointer exception you'll hit loads of results.

Null pointer exceptions are a class or errors that Swift has completely eliminated by having Optional as a type. So let's dig into Optional a bit, and see why that tempting ! operator is so dangerous, shall we?

If you want to declare a variable in Swift you can use either the let or var keyword. If you don't want to assign a value to one of your properties right away you could write something like var episodeName: String? or var episeodeName: Optional<String> (these are equivalent; the former is syntactic sugar for the latter).

This informs the Swift compiler that episodeName might not have a value when we're accessing it. If we don't add the question mark and write var episodeName: String, the episodeName will need to be assigned a value when we initialize the object that contains this property. A third way to declare episodeName is to implicitly unwrap the value: var episodeName: String!. This tells the compiler that the value might be nil after initialization but we are 100% sure that episodeName will get a value before we attempt to access it.

These question mark / exclamation mark semantics also apply to using variables in your code. When you've declared your variable with a questionmark (var episodeName: String?) we are never sure if episodeName is nil or a String. So whenever we want to use this variable we need to unwrap it. The safest way to do this is as follows:

// if let
if let episodeName {
    println(episodeName) // prints episodeName's value
}

// or guard...
guard let episodeName else {
  // episodeName is nil
  return
}

print(episodeName)

However, if you're 100% sure you've set a value, you can tell the Swift compiler that you don't want to explicitly unwrap your value because you know what you're doing and you just want to get your episode’s name by forcing an unwrap:

println(episodeName!)

By adding the exclamation mark after episodeName, we force unwrap it and we can use it's value straight away without an extra if or guard statement. Sounds great, right?

Well.. not quite!

Where's the danger?

If you're writing an application you're sometimes sure that you assign a value to something. For example, you might have written something like:

var show = TVShow()
show.episodeName = apiData.name
show.printEpisodeName()

This code should usually be safe. Before we ask the show for it's episodeName we actually set it so we're always sure that episodeName has a value before we access it. So the implementation of printEpisodeName might be:

func printEpisodeName() {
    println(episodeName!)
}

This shouldn’t crash when we run it. After all, we know what we're doing! We always set the episodeName right after we instantiate our class. What could go wrong, right? Well... besides the fact that we probably should have created an initializer that takes the episodeName, a lot can go wrong.

But then your project matures...

So, our project has been ongoing for a few weeks and we're changing the API. Before, we were guaranteed that the API would always return properly formatted JSON but we've decided that things like the name for an episode isn't guaranteed anymore. In other words, the name can be nil.
We test our app, everything still works when we're navigation to our show page so we're happy. But then.. crash reports come in. Users are livid and to add insult to injury, your manager is suddenly at your desk "What's going on" they ask. The app is crashing. Hard.

What's going on!? Everything was fine before! So we start searching and debugging. And once we manage to reproduce the crash we see what's going on:

Unexpectedly found nil while unwrapping an optional value

And then we remember. The forcefully unwrapped optional in our TVShow class:

func printEpisodeName() {
    println(episodeName!)
}

When we set the episodeName on our tv show, the name we get from the API can be nil. And that's alright because we declared our episodeName like this: var episodeName: String?. Which means that episodeName can be either nil or a String. Luckily, our bug is easily fixed:

func printEpisodeName() {
    if let episodeName {
        println(episodeName)
    } else {
        println("model id is nil")
    }
}

Now we handle the optional value properly, we avoid crashes and an angry manager. Time to get yourself a cup of coffee and tell your manager that you've fixed the error.

In Summary

As we saw in this post it can be tempting to force the unwrappin of a variable when we're pretty sure that we will set it before we use it. But as requirements change it can be easy to overlook situations where a variable can suddenly be nil when we try to access it.

My advice is to (almost) always unwrap optionals properly with an if let or guard let construction. It's the only way to be 100% sure that you're not accidentally accessing a variable whose value is actually nil. More importantly, this will help to prevent future crashes.

So remember kids, always unwrap your optionals in a safe way.

No app is truly complete without some subtle shadows. Especially now that Google's Material Design is showing us that shadows are cool again we need a way to properly add them in our apps. In my previous post I wrote about a way to create a custom UICollectionView layout. There was one problem with that post though, that shadows are incredibly heavy on the iPhone and scrolling stutters.

So can we fix this? The answer is yes and the solution is (surprisingly) easy. A Google search led me to this Stackoverflow question about shadows. The solution I tried first was to simple rasterize my layer but that wasn't what I was looking for. Images started to look very bad and I didn't want that. Another solution that was proposed is to supply the layer with a shadowPath.

What is shadowPath and what does it do?

If you set the shadowPath property it will function as a guide to the shadow that ends up underneath your view. If you don't set this, the view need to be analyzed at runtime to determine where the view is transparent and where it isn't which will result in the eventual shadow shape. This is a pretty costly operation, especially if you do this for about 20 views at a time in a UICollectionView. And even more so if you start scrolling in this view.

Implementing shadowPath

Assuming we're using the code from my previous post there isn't much we have to do. We have to create a circular path that has the same size as the imageView. We know that our imageView get's rendered at 80px by 80px so we can use UIBezierPath with rounded corners to generate a circular path. Let's add this line before we specify the shadows in the CustomCollectionViewCell class:

layer.shadowPath = UIBezierPath(roundedRect: CGRectMake(0, 0, 80, 80), cornerRadius: 40).CGPath

Build and run the project and you should now see butter smooth scrolling instead of the bad scrolling we had before.

Summary

If you want to use shadows on your views then you should probably also set the shadowPath on your view to ensure proper performance. By doing this you can speed up rendering a great deal because otherwise the view will be analyzed at runtime to find out what shape the view has, this is a lot slower than just providing the proper shadow path. Setting the path does not only increase performance but it also allows you to create many fun effects with shadows.

Note:
This blog post has been updated for Xcode 11 and Swift 5 👍🏼
If you’re looking to learn more about the new collection view layout techniques that were introduced in iOS 13, this post should contain everything you need.

If you've ever built an iOS app that uses some kind of grid layout or displays a list in a way that doesn't fit a UITableView you have probably used a UICollectionView. This component allows for very simple grid layout creation and it even allows you to dynamically change layouts with beautiful animations. UICollectionView becomes even more powerful and flexible if you create your own layout by subclassing UICollectionViewLayout.

Recently I had to build a kind of playful, almost grid-like layout. To me, this seemed like the best time to dive straight into subclassing UICollectionViewLayout and create a nice layout. In this post, I will explain how I did it and I'll provide you with a little bit of code so you can start building your own layouts in no-time.

The end result

Since I'm a great fan of cats, we'll be building a collection of cat images. The images will be rounded, they'll have a nice shadow so they look kind of nice and the magic bit is, of course, the slightly offset rows that are provided by the custom UICollectionViewLayout.

The image above illustrates what we'll end up with when we're done. It's quite something, isn't it?

Creating your custom layout

Before we get to build our layout we have to do some set up. Create a new Xcode project and use the Single View Application template. I named my project "CustomCollectionViewLayout" because I'm not very good at coming up with clever names. You can name your project anything you like. Make sure that you pick Storyboard for the layout, we won't be using SwiftUI in this post.

Step one: setting up the interface

Creating the UICollectionView

The first thing you should do is open up the Main.storyboard and drag a UICollectionView out to your View Controller. When you've done this give the collection view a white background color and add constraints to it so it will fit your view nicely. If you're unsure how to do this, size the collection view so that it touches the left, bottom and right edges of the view and it should be aligned underneath the status bar. XCode should provide you with some helpful guides for this. Once your view is sized like this, click in the bottom right corner of your canvas and choose Reset to suggested constraints.

Next, we should connect the collection view to our ViewController class. Open up the assistant editor by pressing the two overlapping circles in your XCode window and make sure that the editor is set automatically use an appropriate file.

Select the UICollectionView, hold ctrl and drag over to the code editor to create an outlet for the UICollectionView. I named mine "collectionView". That's all the setup we need for now.

Creating a UICollectionViewCell

To display our cat images we need to have a UICollectionViewCell with an image inside of it. To do this we can simply create our own UICollectionViewCell and put a UIImageView inside of it.

First, create a new CocoaTouch Class (either press cmd+n or by navigating through the file menu). Name your file CustomCollectionViewCell, make it subclass UICollectionViewCell and check "Also create xib file".

XCode should have created a .swift and .xib file for you. Let's open up the .xib file first and then press the assistant editor button so we have both the .xib and .swift file open at the same time. Drag a UIImageView out into your custom cell and size it so that it fills up the cell exactly. Since we'll be resizing the cell later we should "Reset to suggested constraints" again, just like we did with the UICollectionView earlier. Now select the image, press and hold ctrl and then drag to your swift file to create an outlet for the imageView. I named mine "imageView".

Our example image had rounded corners and a shadow applied so let's write some code to make this happen. All you need is a few lines inside awakeFromNib().

override func awakeFromNib() {
  imageView.layer.cornerRadius = 40
  imageView.clipsToBounds = true
  
  layer.shadowColor = UIColor.black.cgColor
  layer.shadowOffset = CGSize(width: 0, height: 2)
  layer.shadowRadius = 2
  layer.shadowOpacity = 0.8
}

This code is fairly straightforward. First, we apply rounded corners to our imageView. Then we apply a shadow to the cell itself. You can tweak the numbers to change how the cell looks. Did you notice the magic number 40? In an actual app, you might want to find a better solution for this because 40 is half of the cell's eventual size but there's no way to know that unless you came up with all the sizings yourself.

The last thing we have to do is register this custom cell to our UICollectionView. We created an IBOutlet for the UICollectionView earlier by ctrl+dragging from the UICollectionView to the ViewController. Open up ViewController.swift  and add this line to the viewDidLoad method:

collectionView.register(UINib(nibName: "CustomCollectionViewCell", bundle: nil), forCellWithReuseIdentifier:cellIdentifier)

We're using a cellIdentifier  variable here, let's define that as well. Place this code right below your collectionView  outlet:

private let cellIdentifier = "collectionCell"

Allright, that's all. Our UI is fully prepared now. The code you've added to ViewController.swift  should look like this:

@IBOutlet weak var collectionView: UICollectionView!
    
private let cellIdentifier = "collectionCell"

override func viewDidLoad() {
    super.viewDidLoad()
        
    collectionView.register(UINib(nibName: "CustomCollectionViewCell", bundle: nil), forCellWithReuseIdentifier:cellIdentifier)
}

Step two: setting up the UICollectionView dataSource

To get our UICollectionView to display our collection of cat pictures we will need to make sure our UICollectionView knows where to go for its data. To do this, select the connections inspector in the right drawer of XCode and drag the dataSource connector to the ViewController class.

To actually implement the dataSource we should make our ViewController  comply to the UICollectionViewDataSource  protocol. Open up ViewController.swift  and change it's class definition to this:

class ViewController: UIViewController, UICollectionViewDataSource

By adding UICollectionViewDataSource  after the superclass we tell Swift that this class implements the UICollectionViewDataSource protocol. This protocol dictates that we should at least provide our UICollectionView with:

• the amount of sections it should contain
• the amount of items there are in each sections
• cells to display

The following code takes care of all this:

func numberOfSectionsInCollectionView(collectionView: UICollectionView) -> Int {
  return 1
}

func collectionView(_ collectionView: UICollectionView, numberOfItemsInSection section: Int) -> Int {
  return 50
}

func collectionView(_ collectionView: UICollectionView, cellForItemAt indexPath: IndexPath) -> UICollectionViewCell {
  let cell = collectionView.dequeueReusableCell(withReuseIdentifier: cellIdentifier, for: indexPath) as! CustomCollectionViewCell
  
  cell.imageView.image = UIImage(named: "cat_\(indexPath.row%10)")
  
  return cell
}

The collection view will contain a single section with 50 items. Our cell creation code is also fairly straightforward, we dequeue the cell that we've registered before and we forcefully cast it to be a CustomCollectionViewCell. Then we set the imageView.image to one of the cat images you've added to the project earlier. I only added 10 images so I reuse them. To use the next code snippet in your own project, you should add 10 images to your Images.xcassets and name them cat_0.jpg - cat_9.jpg.

If we were to run our app now we'd end up with something like this:

Not quite what we wanted.. but don't worry, we're going to implement our custom layout right now!

Step three: implementing the custom layout

Now that we're all set up it's time to get to hard part; the custom layout! First, create a now Cocoa Touch Class and call it "CustomCollectionViewLayout". It should subclass UICollectionViewFlowLayout. To avoid many small chunks of code I've grouped together some code in sensible groups, I'll show you code first and then explain what it does right after that. Here's the first chunk:

let itemWidth: CGFloat = 80
let itemSpacing: CGFloat = 15
var layoutInfo = [IndexPath: UICollectionViewLayoutAttributes]()
var maxXPos: CGFloat = 0

override init() {
  super.init()
  setup()
}

required init?(coder aDecoder: NSCoder) {
  super.init(coder: aDecoder)
  setup()
}

func setup() {
  // setting up some inherited values
  self.itemSize = CGSize(width: itemWidth, height: itemWidth)
  self.minimumInteritemSpacing = itemSpacing
  self.minimumLineSpacing = itemSpacing
  self.scrollDirection = .horizontal
}

This first section is responsible for the initial setup. It sets up some sizing values (remember that magic number 40 in our cell?) and it creates an array that we'll use to store our layout in. When you're creating a collection view that changes often or contains a lot of items you might not want to use this technique but since we have a relatively small collection that doesn't change often we can cache our entire layout. There's also a variable to hold the maxXPos , we'll use that to calculate the collectionView's content size later. In the setup() function we configure the layout, these properties are inherited from the UICollectionViewFlowLayout and allow us to set up spacings and a scrollDirection. In this case we're not really using the spacings but I think it's good practice to set them up anyway.

override func prepare() {
  layoutInfo = [IndexPath: UICollectionViewLayoutAttributes]()
  for i in (0..<(self.collectionView?.numberOfItems(inSection: 0) ?? 0)) {
    let indexPath = IndexPath(row: i, section: 0)
    let itemAttributes = UICollectionViewLayoutAttributes(forCellWith: indexPath)
    itemAttributes.frame = frameForItemAtIndexPath(indexPath)
    if itemAttributes.frame.origin.x > maxXPos {
      maxXPos = itemAttributes.frame.origin.x
    }
    layoutInfo[indexPath] = itemAttributes
  }
}

func frameForItemAtIndexPath(_ indexPath: IndexPath) -> CGRect {
  let maxHeight = self.collectionView!.frame.height - 20
  let numRows = floor((maxHeight+self.minimumLineSpacing)/(itemWidth+self.minimumLineSpacing))
  
  let currentColumn = floor(CGFloat(indexPath.row)/numRows)
  let currentRow = CGFloat(indexPath.row).truncatingRemainder(dividingBy: numRows)
  
  let xPos = currentRow.truncatingRemainder(dividingBy: 2) == 0 ? currentColumn*(itemWidth+self.minimumInteritemSpacing) : currentColumn*(itemWidth+self.minimumInteritemSpacing)+itemWidth*0.25
  let yPos = currentRow*(itemWidth+self.minimumLineSpacing)+10

  return CGRect(x: xPos, y: yPos, width: itemWidth, height: itemWidth)
}

This piece of code comes after our initial setup, it overrides the prepareLayout  function which is called before the cells are actually going to need their layout. This allows us to pre-calculate our entire layout. Which is exactly what we want to do for this use case. There's a loop inside this function that uses the collectionView.numberOfItemsInSection function to find out how many items it is going to display. It then initializes layoutAttributes for the item at the current NSIndexPath and it calls frameForItemAtIndexPath. To calculate the item's frame. Next up is a check to determine of the x position for this item is the largest x position in our collection and then it stores the itemAttributes in our layout cache.

The frameForItemAtIndexPath function uses the height of our collectionView to determine the amount of cells it can fit into a single column, then it determines how many rows there will be in our collection and based on that it calculates the x and y position for the item. Every other item will be offset somewhat to the right, we use the % operator and a ternary for that. If currentRow % 2 == 0 the xPos is equal to currentColumn(itemWidth+self.minimumInteritemSpacing), otherwise it will be equal to currentColumn(itemWidth+self.minimumInteritemSpacing)+itemWidth*0.25. And finally we return a CGRect with the correct size and position values.

This last snippet of code actually provides our collection with the layout:

override func layoutAttributesForItem(at indexPath: IndexPath) -> UICollectionViewLayoutAttributes? {
  return layoutInfo[indexPath]
}

override func layoutAttributesForElements(in rect: CGRect) -> [UICollectionViewLayoutAttributes]? {
  var allAttributes: [UICollectionViewLayoutAttributes] = [UICollectionViewLayoutAttributes]()
  
  for (_, attributes) in layoutInfo {
    if rect.intersects(attributes.frame) {
      allAttributes.append(attributes)
    }
  }
  
  return allAttributes
}

override var collectionViewContentSize: CGSize {
  let collectionViewHeight = self.collectionView!.frame.height
  let contentWidth: CGFloat = maxXPos + itemWidth
  
  return CGSize(width: contentWidth, height: collectionViewHeight)
}

The first method, layoutAttributesForItemAtIndexPath simply returns the layout attributes that belong to the passed IndexPath. Fairly straightforward. Next, we have layoutAttributesForElementsInRect. This method is somewhat more complex because we get passed a CGRect and we have to determine which items are inside of that area. To do this we loop over our layoutInfo object, we compare the rects and we return all intersecting items.

Finally, we calculate the collectionView's contentSize. The contentWidth is equal to our maxXPos + itemWidth and the height is the same as the collectionView's height.

Step four: using the custom layout

The final step in this tutorial is to actually make the UICollectionView use our custom layout. To make this happen, select the Collection View Flow Layout object that is associated with your UICollectionView in your Main.storyboard and change it's class to CustomCollectionViewLayout.

Now build and run your app, you should see something like the image I showed you at the beginning of this post.

In conclusion

I hope this post is helpful to some of you out there. I had a lot of fun today figuring out how to do this myself and I figured there's probably more people out there who are looking for cool ways to implement UICollectionView and use custom layouts.

If you want to learn more about collection view layouts, check out my post called Using compositional collection view layouts in iOS 13.

The code for this project can be found on GitHub and if you want to reach out to me, I'm on Twitter.