README.md

Caravel

An event bus for sending messages between UIWebView and embedded JS. Made with pure Swift.

Features

• Easy event bus system
• Multiple bus support
• When Ready event: do not miss any event from your lovely Swift controller!
• iOS ~> JavaScript supported types:
  • Bool
  • Int
  • Float
  • Double
  • String
  • NSArray
  • NSDictionary
• JavaScript ~> iOS supported types:
  • Int
  • Double
  • String
  • Array (available as a NSArray)
  • Object (available as a NSDictionary)

Installation

Install Caravel using CocoaPods:

pod 'Caravel'

Otherwise, you can install it as a submodule of your project.

Once done, you should find a caravel.min.js file in either the Pod or the submodule. Add this file to your project. Then, in each HTML page you have, load it before running your main script:

<script type="text/javascript" src="caravel.min.js"></script>

Get started

Caravel allows developers to communicate between their UIWebView and the embedded JS. You can send any kind of message between those two folks.

Have a glance at this super simple sample. Let's start with the iOS part:

import Caravel

class MyController: UIViewController {
    @IBOutlet weak var webView: UIWebView!
    
    func viewDidLoad() {
        super.viewDidLoad()
        
        Caravel.getDefault().whenReady() { bus in
            bus.post("AnEvent", anArray: [1, 2, 3])
        }
        
        // Load web view content below
    }
}

And now, in your JS:

Caravel.getDefault().register("AnEvent", function(name, data) {
    alert('I received this array: ' + data);
});

And voilà!

API

Swift - Caravel class

/**
 * Returns the default bus
 */
static func getDefault(webView: UIWebView) -> Caravel

/**
 * Returns custom bus
 */
static func get(name: String, webView: UIWebView) -> Caravel

/**
 * Returns the current bus when its JS counterpart is ready
 */
func whenReady(callback: (Caravel) -> Void)

/**
 * Posts event without any argument
 */
func post(eventName: String)

/**
 * Posts event with extra data
 */
func post(eventName: String, anObject: AnyObject)

NB: Caravel is smart enough for serializing nested objects (eg. an array wrapped into a dictionary) when posting an event. However, this serialization only works if nested types are supported ones.

/**
 * Subscribes to provided event. Callback is run with the event's name and extra data
 */
func register(eventName: String, callback: (String, AnyObject?) -> Void)

When receiving an event, you have to cast your data to the type you except. This cast is safe.

JS - Caravel class

/**
 * Returns default bus
 */
static function getDefault()

/**
 * Returns custom bus
 */
static function get(name)

/**
 * Subscribes to provided event. Callback is called with event name first, then extra data if any
 */
static function register(name, callback)

/**
 * Posts event. Data are optional
 */
static function post(name, data)

Troubleshooting

I have my custom UIWebViewDelegate. What should I do?

Caravel saves the current delegate, if any, before setting its own. So, if you would like to use your custom one, you have to set it before any call to Caravel.

Reserved names

CaravelInit is an internal event, sent by the JS part for triggering the whenReady method.

Also, the default bus is named default. If you use that name for a custom bus, Caravel will automatically use the default one.