RELEASE 1.2.0

Merge branch 'develop'

.gitignore

@@ -33,3 +33,10 @@ Pods
 */*/bin/
 */*/gen/
 */*/build/
+
+# Web
+.idea
+
+# Development
+node_modules
+bower_components

Hybridge.podspec

@@ -0,0 +1,26 @@
+Pod::Spec.new do |s|
+  s.name         = "Hybridge"
+  s.version      = "1.2.0"
+  s.summary      = "Yet another javascript / mobile native simple bridge for hybrid apps, back and forth..."
+
+  s.description  = <<-DESC
+                   When developing hybrid apps surely you'll need to access different native features and resources. 
+                   Out there are plenty of bridge solutions. Hybridge tries to make easy communication and data 
+                   exchanging between native (iOS & Android) and Javascript worlds, avoiding too much overhead.
+                   DESC
+  s.homepage     = "https://github.com/telefonicaid/tdigital-hybridge"
+
+  s.license      = { :type => "Affero GNU GPL v3", :file => "LICENSE.txt" }
+
+  s.authors  = { 'David Garcia' => 'davidgarsan@gmail.com', 'Guillermo Gonzalez' => 'gonzalezreal@icloud.com' }
+
+  s.platform     = :ios
+  s.ios.deployment_target = "6.0"
+  s.source       = { :git => "https://github.com/telefonicaid/tdigital-hybridge.git", :tag => "1.2.0" }
+
+  s.source_files = "ios/Hybridge/Hybridge/*.{h,m}"
+  s.private_header_files = "ios/Hybridge/Hybridge/HYBURLProtocol.h", "ios/Hybridge/Hybridge/NSString+Hybridge.h"
+
+  s.frameworks = "Foundation", "UIKit"
+  s.requires_arc = true
+end

README.md

@@ -5,9 +5,10 @@ Yet another javascript / mobile native simple bridge for hybrid apps, back and f
 ## <a name='index'>Index</a>
 
   1. [Why?](#why)
-  1. [Getting Started](#start)
-   * [Dependencies](#dependencies)
-      * [Javascript](#dependencies_javascript)
+  1. [Installation](#installation)
+   * [Javascript](#installation_javascript)
+   * [Android](#installation_android)
+   * [iOS](#installation_ios)
   1. [Usage](#usage)
    * [Javascript](#usage_javascript)
    * [Android](#usage_android)
@@ -31,13 +32,40 @@ Hybridge tries to make easy communication and data exchanging between native (iO
 
 **[[⬆]](#index)**
 
-## <a name='start'>Getting Started</a>
-Firstly, get the code by downloading the zip or cloning the project into your local.
+## <a name='installation'>Installation</a>
+Hybridge follows [semantic versioning](http://semver.org/). In the `boilerplate` directory you can find examples of how to get running in the different platforms.
 
-### <a name='dependencies'>Dependencies</a>
-#### <a name='dependencies_javascript'>Javascript</a>
-Hybridge works in an AMD fashion, so you'll need [RequireJS](http://requirejs.org) for the loading.
-You'll also need [JQuery](http://jquery.com) (version 1.5 or newer) for the Javascript part since [Deferred](http://api.jquery.com/category/deferred-object) object is used intensively.
+### <a name='installation_javascript'>Javascript</a>
+
+Since v1.2.0, `hybridge` is available in [bower](http://bower.io/). Bower will install `hybridge` itself and all its dependencies.
+```sh
+bower install --save hybridge
+```
+
+Add it to your HTML
+```html
+<script type="text/javascript" src="bower_components/hybridge/js/hybridge.js"></script>
+```
+
+You can manually download the javascript [js/hybridge.js](js/hybridge.js) and use the traditional way.
+
+Hybridge works in both an AMD/Vanilla javascript fashion. For vanilla javascript, it's available in `window.Hybridge` variable.
+You'll also need [JQuery](http://jquery.com) (version 1.8.3 or newer) for the Javascript part since [Deferred](http://api.jquery.com/category/deferred-object) object is used intensively.
+
+
+### <a name='installation_android'>Android</a>
+
+You can build your own Hybridge, but you can start with the latest version included at [hybridge.jar](boilerplate/android/HybridgeBoilerplate/libs/hybridge-1.2.0.jar) in the boilerplate code.
+
+### <a name='installation_ios'>iOS</a>
+
+Add the following to your `Podfile` and run `$ pod install`.
+
+``` ruby
+pod 'Hybridge'
+```
+
+If you don't have CocoaPods installed or integrated into your project, you can learn how to do so [here](http://cocoapods.org).
 
 **[[⬆]](#index)**
 
@@ -57,13 +85,12 @@ Load `hybridge.js` as a module in your AMD code. Simplest setup:
   require.config({
       baseUrl: 'js/lib',
       paths: {
-        jquery: 'jquery',
-        hybridge: 'hybridge'
+        jquery: 'bower_components/jquery/dist/jquery',
+        hybridge: 'bower_components/hybridge/js/hybridge'
       }
   });
 
-  requirejs(['hybridge'],
-    function (Hybridge) {
+  require(['hybridge'], function (Hybridge) {
       Hybridge.init({
         'environment' : 'ios'
         }
@@ -116,6 +143,7 @@ public class DownloadTask extends AsyncTask<Object, Void, JSONObject> {
 
     private JsPromptResult result;
     private Context context;
+    private HybridgeBroadcaster hybridge;
 
     public DownloadTask(Context context) {
         this.context = context;
@@ -125,6 +153,7 @@ public class DownloadTask extends AsyncTask<Object, Void, JSONObject> {
     protected JSONObject doInBackground(Object... params) {
         JSONObject json = (JSONObject) params[0];
         result = (JsPromptResult) params[1];
+        hybridge = (HybridgeBroadcaster) params[2];
         // Process download
         ...
         return json;
@@ -139,51 +168,79 @@ webView.setWebViewClient(new HybridgeWebViewClient(JsActionImpl.values()));
 webView.setWebChromeClient(new HybridgeWebChromeClient(JsActionImpl.values()));
 ```
 
-* Implement `Observable` in your WebView and subscribe it in order to notificate Javascript the events received from `HybridgeBroadcaster`:
+* Implement `Observable` in your WebView fragment and subscribe it in order to notificate Javascript the events received from `HybridgeBroadcaster`:
 ```java
-HybridgeBroadcaster.getInstance().addObserver(this);
+HybridgeBroadcaster.getInstance(mWebView).addObserver(this);
 ...
 @Override
 public void update(Observable observable, Object data) {
     JSONObject json = (JSONObject) data;
     if (json.has(HybridgeConst.EVENT_NAME)) {
         try {
-            HybridgeBroadcaster.getInstance().fireJavascriptEvent(mWebView, (Event) json.get(HybridgeConst.EVENT_NAME), json);
+            HybridgeBroadcaster.getInstance(mWebView).fireJavascriptEvent(mWebView, (Event) json.get(HybridgeConst.EVENT_NAME), json);
         } catch (JSONException e) {
             Log.e(mTag, "Problem with JSON object " + e.getMessage());
         }
     } else {
-        HybridgeBroadcaster.getInstance().fireMessage(mWebView, json);
+        HybridgeBroadcaster.getInstance(mWebView).fireMessage(mWebView, json);
     }
 }
 ```
 
 **[[⬆]](#index)**
 
 ### <a name='usage_ios'>iOS</a>
-* Compile the sources and copy the Hybridge static lib in your project `HYBHybridge.h` and `libHybridge.a`.
-* Import `HYBHybridge.h` in your *UIWebView* controller.
-* Bind the Hybridge singleton:
 
-```objective-c
-_hybridge = [HYBHybridge sharedInstance]
+#### Creating a Web View Controller
+Hybridge provides `HYBWebViewController`, a convenience view controller that hosts both a web view and a bridge object to communicate with it. Users are encouraged to subclass `HYBWebViewController` and specify any supported bridge actions.
+
+```objc
+#import <Hybridge/Hybridge.h>
+
+@interface MyWebViewController : HYBWebViewController
+@end
 ```
-* Implements your native `actions` in *blocks* with the handler `HybridgeHandlerBlock_t`:
-
-```objective-c
-HybridgeHandlerBlock_t downloadHandler = ^(NSURLProtocol *url, NSString *data, NSHTTPURLResponse *response) {
-    NSDictionary *params = [_parser objectWithString:data];
-    // Handle download with data from Javascript request
-    ...
-};
+
+```objc
+...
+- (NSArray *)bridgeActions:(HYBBridge *)bridge {
+    return @[@"some_action", @"some_other_action"];
+}
 ```
-* You'll parse the JSON `data` sent from Javascript as seen in the previous code snippet.
-* Finally, subscribe each of your `actions` to the Hybridge by binding to the name you'll use to invoke it from Javascript.
 
-```objective-c
-[_hybridge subscribeAction:@"download" withHandler:downloadHandler];
+There are two different ways to handle bridge actions:
+
+1. Override `-bridgeDidReceiveAction:data:`
+
+```objc
+- (NSDictionary *)bridgeDidReceiveAction:(NSString *)action data:(NSDictionary *)data {
+    if ([action isEqualToString:@"some_action"]) {
+        // Handle 'some_action'
+    } else if ([action isEqualToString:@"some_other_action"]) {
+        // Handle 'some_other_action'
+    }
+
+    // Return a JSON dictionary or `nil`
+    return nil;
+}
 ```
 
+2. Implement a method with a special signature for each supported action. The bridge will look for methods with the signature `- (NSDictionary *)handle<YourActionInCamelCase>WithData:(NSDictionary *)data`
+
+```objc
+- (NSDictionary *)handleSomeActionWithData:(NSDictionary *)data {
+    // Handle 'some_action'
+    return @{ @"foo": @"bar" };
+}
+
+- (NSDictionary *)handleSomeOtherActionWithData:(NSDictionary *)data {
+    // Handle 'some_other_action'
+    return nil;
+}
+```
+
+Note the **CamelCase** in the method signature. If your action is named `some_action`, this becomes `SomeAction` in the method signature.
+
 **[[⬆]](#index)**
 
 ### <a name='usage_boilerplate'>Boilerplate</a>
@@ -206,15 +263,16 @@ You can communicate to Javascript from Android/iOS by triggering any of the defi
 * **message**: Send arbitrary data when required.
 
 ### <a name='events_android'>Android</a>
-Use *HybridgeBroadcaster* singleton to trigger events in Javascript:
+Use *HybridgeBroadcaster* instance to trigger events in Javascript:
 ```java
-HybridgeBroadcaster.getInstance().fireJavascriptEvent(webView, Event.READY, jsonData);
+HybridgeBroadcaster.getInstance(mWebView).fireJavascriptEvent(webView, Event.READY, jsonData);
 ```
 
 ### <a name='events_ios'>iOS</a>
-Use *Hybridge* singleton to trigger events in Javascript:
-```objective-c
-[_hybridge fireEventInWebView:kHybridgeEventReady data:@"{foo : \"data\"}" web:self.webview]
+Hybridge provides an `UIWebView` category that sports a convenience method to trigger events on the Javascript side.
+
+```objc
+[self.webView hyb_fireEvent:HYBEventMessage data:@{ @"foo": @"bar" }];
 ```
 
 ### <a name='events_javascript'>Javascript</a>
@@ -264,6 +322,11 @@ let's enumerate the available methods and properties from the Hybridge Javascrip
  Provides the way to communicate from Javascript to native side. An `action` parameter is required in order to execute an implemented native task.
  Returns a [JQuery](http://jquery.com) [Promise](http://api.jquery.com/Types/#Promise) containing data returned from native or custom error.
  You can add a second function parameter `fallback` in case something goes wrong and you want to supply aditional user feedback as well as update your UI.
+* **ready(callback:Function)**
+ Function that executes the callback function once Hybridge has become enabled. If Hybridge was enabled at calling time,
+ the callback is executed inmediatly. The main difference with `addListener('ready', handler)` event subscription
+ is that the event handler never becomes executed when the subscription happens and Hybridge was enabled
+
 
 ### <a name='api_properties'>Properties</a>
 * **errors** Container object of customs errors returned by the Hybridge:

android/Hybridge/AndroidManifest.xml

@@ -1,9 +1,9 @@
 <?xml version="1.0" encoding="utf-8"?>
 <manifest xmlns:android="http://schemas.android.com/apk/res/android"
     package="com.pdi.hybridge"
-    android:versionCode="1"
-    android:versionName="1.0" >
+    android:versionCode="120"
+    android:versionName="1.2.0" >
 
     <uses-sdk android:minSdkVersion="12" />
 
-</manifest>
+</manifest>