The source code accompanying this blog post is on github: https://github.com/olegam/RACCommandExample
Is RACCommand your new best friend?
RACCommand is one of the essential parts of ReactiveCocoa that eventually can save you a lot of time and help make your iOS or OS X apps more robust.
I’ve met several people new to ReactiveCocoa (hereafter abbreviated RAC) who don’t entirely understand how
RACCommand works and when it should be used. So I thought it would be useful to write a small introduction to shed some light. The official documentation doesn’t give many examples of how to use RACCommand, but the comments in the header file are great. However, they may be hard to understand if you’re new to RAC.
RACCommand class is used to represent the execution of some action. Often the execution is triggered by some action in the UI. Like when the user taps a button.
RACCommand instances can be configured to handle reasoning about when it can be executed. This can easily be bound to the UI and the command will also make sure it doesn’t start executing when it’s not enabled. A commonly used strategy for when the command can execute is to leave the
allowsConcurrentExecution at it default value of
NO. This will make sure the command doesn’t start executing again if it’s already executing. The result of command execution is represented as a
RACSignal and can hence yield results with
next: (representing new values or results),
error:. I’ll show how this is used below.
The example app
Let’s assume we are making a simple iOS app that will let the user subscribe to an email list. In the simplest form we will have a text field and a button. When the user has entered his email and taps the button the email address should be posted to some webservice. Easy enough. However there are some edge cases that we should make sure to handle to provide the best experience. What happens if the user taps the button twice? How are errors handled? What if the email is invalid?
RACCommand can help us handle those cases. I’ve implemented a small app to demonstrate the concepts discussed in this post.
Get the source code for the example app here: https://github.com/olegam/RACCommandExample
With a very simple view controller the app also demonstrates a way to practice the MVVM pattern in iOS apps. Basically the view controller sets up the view hierarchy and instantiates an instance of the view model.
1 2 3 4 5
The above method (called from
viewDidLoad) creates the bindings between the view and the view model. All the interesting stuff is in the view model. It has the following interface:
1 2 3 4 5 6 7 8 9 10 11
The RACCommand property exposed here is what the rest of this post will be about. The two other string properties were bound to properties of the view as shown above. The full implementation of the view model looks like this:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67
This might seem like a big chunk so let’s go through it in smaller parts. The
RACCommand that we are most interested in is created like this:
1 2 3 4 5 6 7 8 9
The command is initialized with an
enabledSignal parameter. This is a signal indicating when the command can execute. In our case it should be allowed to execute when the email address entered by the user is valid. The
self.emailValidSignal is a signal that sends a
NO or a
YES every time the email changes.
signalBlock parameter is invoked every time the command needs to execute. The block should return a signal representing the execution. Since we leave the default property of
NO the command will watch this signal and not allow any new executions before the execution in progress completes.
Because the command is set on the button’s
rac_command property defined in the
UIButtton+RACCommandSupport category the button will automatically change between the enabled and disabled state based on when the command can execute.
Also the command will automatically execute when the button is tapped by the user. We get all this for free with
RACCommand. If you need to execute the command manually you can do this by messaging
-[RACCommand execute:]. The argument is an optional input. We don’t use it here, but it is often very useful (the button sends itself as input when it calls
-execute: method is also one of the places you can hook in to watch the status of the execution. You could potentially do something like this:
1 2 3
In our example the button executes the command for us (so we don’t call
-execute:) and hence we have to listen for another property of the command in order to update the UI when the command executes. There are several opportunities to chose between here. And this can maybe be a little confusing. The
executionSignals property of
RACCommand is a signal that sends a
next: every time the commands start executing. The argument is the signal created by the command. So it’s a signal of signals. We use that in the
mapSubscribeCommandStateToStatusMessage method of the view model to get a signal with a string value every time the command is started:
1 2 3
To get a similar signal with a string every time the command completes execution we have to do a little more work if we want to be purely functional:
1 2 3 4 5 6 7
flattenMap: method used above invokes a block with the
subscribeSignal when the command executes. This block returns a new signal and it’s values are passed down into the resulting signal. The
materialize operator let’s us get a signal of
RACEvents (ie. the
error: messages are delivered as
RACEvent instances as
next: values on the resulting signal). We can then filter those events to only get the ones from when the signal completes and in that case map it to a string value. Did I loose you here? I hope not, but you may need to look up the documentation of flattenMap: and materialize to better understand what they do.
We could have implemented this behavior in a different way that is less functional, but maybe easier to understand:
1 2 3 4 5 6 7
However, I don’t like the above implementation as it involves side effects in the blocks. This also has the disadvantage of referring and retaining
self in the block. Thus I have to use the
@strongify macros (defined in the
libextobjc pod) to avoid a retain cycle. So better just avoid side effects altogether when possible as I did with the original implementation.
There is an important details to note about the
executionSignals property. The signals sent here do not include error events. For those there is a special
errors property. A signal that sends any error during execution of the command as a
next:. The errors are not sent as regular
error: events as that would terminate the signal. We can easily map the the errors to string messages:
1 2 3
Now when we have 3 signals with status messages we want to show to the user we can merge them into one signal and bind that to the
statusMessage property of the view model (bound to the
statusLabel.text property of the view controller).
So this was an example of how a
RACCommand can be used in practice in an iOS app. I think this way of implementing logic has many advantages over the way many people would implement it with a
UITextFieldDelegate in the view controller and lots of state stored in ivars or properties.
Other RACCommand details of interest
RACCommand has an
executing property that is actually a signal sending
execute: is invoked and
NO when it terminates. Upon subscription the signal will send it’s current value. If you just need to get the current value and don’t want a signal, you can get it immediately like this:
enabled property is also a signal sending
NO. It will send
NO when the command was created with an
enabledSignal and that signal sends a
NO or if the signal is executing and
allowsConcurrentExecutions is set to
If you try to message
-execute: on a signal that is not enabled it will immediately send an error, but that error will not be sent to the
-execute: method will automatically subscribe to the original signal and multicast it. This basically means that you do not have to subscribe to the returned signal, but if you do so you should not be afraid of side effects happening twice.