flok 0.0.100 → 0.0.101

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 114477d327897a115f580aa076cb7190f54e5640
-  data.tar.gz: aa8d1cd9e4b91c02c9e53a7e111ff4d12bd08a63
+  metadata.gz: 1d6171c859ceb0102173aab274f388008d70a31a
+  data.tar.gz: a8a1e2a1039caa0157507720ca5991413404d43b
 SHA512:
-  metadata.gz: 7279341e6bd55b6629e228b17c079f012136dac5fe70746d8162fc959d178dca173ab15908030e3302f1e0ee28156f0397095cc883c9b518f70ddc0570799d56
-  data.tar.gz: 12d5b4834e74ccc6b9d6a6e277641703f1b2bcdebaf71b30961101b3d6b64ae684a11d65cd538b906d7e5149b9e22d22071a0884d16c0d73dc4151749f3a432b
+  metadata.gz: 9f90608d9d9272f1ab7bd6d2fc1731d6d812c5ac68fb359f8dcc4cf8d0e58ca1fb08f8d96ad5f91744b253b33ac3005f219da27850c47bce6311aafe2942f049
+  data.tar.gz: 40ff86e7e1ca0ac862a981e6a11d01d139958dbb1702de083276736505c1b97462fcbd8f7e77928318af61ddd91921c9a29fc22b807096788bd25d6e7598b935

data/app/drivers/chrome/README.md

@@ -64,8 +64,13 @@ var TestController = function() {
 $(document).ready(function() {
   regController("__test__", TestController);
 });
+
 ```
 
+### Handling hook events
+onHookEvent("test", function(params) {
+});
+
 ### DOM helpers
 ```html
 <!-- This will place the contents of context.foo into the divider -->
@@ -80,6 +85,7 @@ $(document).ready(function() {
 ### ERB Compliation
 The final `chrome.js` file is run through an `ERB` compiler that contains the variables:
   * `@debug` - True if `FLOK_ENV=DEBUG`
+  * `@spec` - True if you are running the spec task in the Rakefile
   * `@release` - True if `FLOK_ENV=RELEASE`
   * `@mods` - A list of active kernel modules listed from `config.yml`
 

data/app/drivers/chrome/Rakefile

@@ -40,6 +40,7 @@ task :spec do
   #Build the driver
   ENV['BUILD_PATH'] = "../../../products/chrome/drivers/"
   ENV['FLOK_ENV'] = 'DEBUG'
+  ENV['FLOK_CHROME_SPEC'] = 'TRUE'
   system('rake build')
 
   recipe = Cakery.new("./cakery/spec.js.erb") do |f|

data/app/drivers/chrome/build_context.rb

@@ -5,6 +5,7 @@ module Chrome
     def initialize
       @debug = (ENV['FLOK_ENV'] == "DEBUG")
       @release = (ENV['FLOK_ENV'] == "RELEASE")
+      @spec = (ENV['FLOK_CHROME_SPEC'] == "TRUE")
       Dir.chdir File.join(File.dirname(__FILE__), "../../../") do
         @mods = Flok::Platform.mods(ENV['FLOK_ENV'])
       end

data/app/drivers/chrome/config.yml

@@ -11,6 +11,8 @@ DEBUG:
     - persist
     - timer
     - rtc
+    - hook
+    - dlink
   defines:
     - mem_pager
     - sockio_pager
@@ -25,6 +27,8 @@ RELEASE:
     - persist
     - timer
     - rtc
+    - hook
+    - dlink
   defines:
     - mem_pager
     - sockio_pager

data/app/drivers/chrome/spec/spec/dlink_spec.js

@@ -0,0 +1,15 @@
+//Tests whether dlink_init will transmit the correct information
+
+QUnit.test("dlink_init does notify the dlink system with the proper address", function(assert) {
+  var done = assert.async();
+
+  //Hijack the int event function
+  window.int_dispatch = function(q) {
+    int_dispatch_res = q;
+  }
+
+  dlink_init();
+
+  assert.equal(JSON.stringify(int_dispatch_res), JSON.stringify([2, "int_dlink_notify", "http://test.com:80/test", {"foo": "bar"}]), "Matches");
+  done();
+});

data/app/drivers/chrome/spec/spec/hook_spec.js

@@ -0,0 +1,24 @@
+QUnit.test("When a hook_event is received, it is relayed to the appropriate function handler if available", function(assert) {
+  //Register a hook event handler
+  onHookEvent("test", function(params) {
+    test_hook_fired = true;
+    test_hook_params = params;
+  });
+
+  onHookEvent("hello", function(params) {
+    hello_hook_fired = true;
+    hello_hook_params = params;
+  });
+
+  //Test two seperate hook events
+  if_hook_event("test", {foo: "bar"});
+  if_hook_event("hello", {hello: "world"});
+
+  //Test an event that has no handler
+  if_hook_event("no_such_handler", {test: "test"});
+
+  assert.equal(test_hook_fired, true, "test hook was fired, got: ", test_hook_fired);
+  assert.equal(JSON.stringify(test_hook_params), JSON.stringify({foo: "bar"}), "test hook was fired with params {foo: bar}, got: ", JSON.stringify(test_hook_params));
+  assert.equal(hello_hook_fired, true, "hello hook was fired, got: ", hello_hook_fired);
+  assert.equal(JSON.stringify(hello_hook_params), JSON.stringify({hello: "world"}), "hello hook was fired with params {foo: bar}, got: ", JSON.stringify(hello_hook_params));
+});

data/app/drivers/chrome/src/dlink.js

@@ -0,0 +1,28 @@
+
+//When the page first loads, send the current URL
+function dlink_init() {
+  //Get parameters
+  var params = {};
+  var parts = <%= @spec ? "dlink_spec_window" : "window" %>.location.href.replace(/[?&]+([^=&]+)=([^&]*)/gi, function(m,key,value) {
+    params[key] = value;
+  });
+
+  //Get URL portion
+  var url = <%= @spec ? "dlink_spec_window" : "window" %>.location.protocol + '//' + <%= @spec ? "dlink_spec_window" : "window" %>.location.host + <%= @spec ? "dlink_spec_window" : "window" %>.location.pathname;
+
+  //Notify dlink
+  int_dispatch([2, "int_dlink_notify", url, params]);
+}
+
+//The window.location struct does not work in phantomJS so we mock it during debugs
+<% if @spec %>
+  dlink_spec_window = {
+    location: {
+      protocol: "http:",
+      host: "test.com:80",
+      pathname: "/test",
+      href: "http://test.com:80/test?foo=bar"
+    }
+  };
+<% end %>
+

data/app/drivers/chrome/src/hook.js

@@ -0,0 +1,29 @@
+//Driver side interface
+///////////////////////////////////////////////////////////////////////////////////////////////////////////
+function if_hook_event(name, info) {
+  <% if @debug %>
+    if_hook_spec_dump_rcvd_events_log.push({name: name, info: info});
+  <% end %>
+
+  //Call the appropriate registered handler
+  if (hookEventHandlers[name] !== undefined) {
+    hookEventHandlers[name](info);
+  }
+}
+
+<% if @debug %>
+  //Track all events sent to if_hook_event
+  var if_hook_spec_dump_rcvd_events_log = []
+  function if_hook_spec_dump_rcvd_events() {
+    int_dispatch([1, "if_hook_spec_dump_rcvd_events_res", if_hook_spec_dump_rcvd_events_log]);
+  }
+<% end %>
+///////////////////////////////////////////////////////////////////////////////////////////////////////////
+
+//User helpers
+///////////////////////////////////////////////////////////////////////////////////////////////////////////
+var hookEventHandlers = {};
+function onHookEvent(eventName, handler) {
+  hookEventHandlers[eventName] = handler;
+}
+///////////////////////////////////////////////////////////////////////////////////////////////////////////

data/app/kern/mod/dlink.js

@@ -0,0 +1,16 @@
+function int_dlink_notify(url, params) {
+  <% if @debug %>
+    int_dlink_spec_last_request = [url, params];
+  <% end %>
+
+  //Currently sends off to the sister dlink-service by default
+  dlink_notify_handler(url, params);
+}
+
+//Spec tracks the last given notify request
+<% if @debug %>
+int_dlink_spec_last_request = null;
+function get_int_dlink_spec() {
+  SEND("main", "get_int_dlink_spec", int_dlink_spec_last_request);
+}
+<% end %>

data/app/kern/mod/event.js

@@ -5,6 +5,10 @@ evt = {};
 edefer_q = [];
 
 function int_event(ep, event_name, info) {
+  <% if @debug %>
+    if (ep.constructor !== String && ep.constructor !== Number) { throw "int_event was given either something that wasn't a string or number for ep: '" + (ep.constructor) + "' and the value was: '" + ep + "'"};
+  <% end %>
+
   var f = evt[ep];
   if (f != undefined) {
     f(ep, event_name, info);
@@ -23,6 +27,9 @@ function dereg_evt(ep) {
 }
 
 function int_event_defer(ep, ename, info) {
+  <% if @debug %>
+    if (ep.constructor !== String && ep.constructor !== Number) { throw "int_event_defer was given either something that wasn't a string or number for ep: '" + (ep.constructor) + "' and the value was: '" + ep + "'"};
+  <% end %>
   edefer_q.push(ep);
   edefer_q.push(ename);
   edefer_q.push(info);

data/app/kern/mod/hook.js

@@ -0,0 +1 @@
+//Stub

data/app/kern/services/dlink.rb

@@ -0,0 +1,25 @@
+service :dlink do
+  global %{
+    //Static from the dlink module itself, this is a sister service
+    function dlink_notify_handler(url, params) {
+      //Notify all view controllers
+      var cbps = Object.keys(dlink_sessions);
+      var einfo = {url: url, params: params};
+      for (var i = 0; i < cbps.length; ++i) {
+        int_event_defer(parseInt(cbps[i]), "dlink_req", einfo);
+      }
+    }
+  }
+
+  on_wakeup %{
+ }
+
+  on_sleep %{
+  }
+
+  on_connect %{
+  }
+
+  on_disconnect %{
+  }
+end

data/bin/flok

@@ -54,6 +54,9 @@ class FlokCLI < Thor
     #4. Move ./app/scripts/*.js into `./products/$PLATFORM/./glob/scripts.js`
     Flok.src_glob("js", './app/scripts', File.join(local_products_path, platform, "./glob/scripts.js"))
 
+    #Save the current local user's project directory to reference
+    user_project_dir = Dir.pwd
+
     #We are now inside the platform folder
     Dir.chdir File.join(local_products_path, platform) do
       #3. Put user_compiler_js in glob folder and services into ./services/user_services.rb
@@ -70,15 +73,21 @@ class FlokCLI < Thor
       FileUtils.cp "application.js", "glob/application.js"
       FileUtils.rm "application.js"
 
-      #7. Combine application.js and user_compiler.js.erb and services.js and scripts.js
-      File.open "glob/application_user.js.erb", "w" do |f|
+      #7. The local project `./products/$PLATFORM/glob/application.js` and `./products/$PLATFORM/glob/user_compiler.js` and `./products/$PLATFORM/glob/services.js` and `./products/$PLATFORM/glob/scripts.js`  are merged into `./products/$PLATFORM/glob/application_user.js.erb.hooks`.
+      File.open "glob/application_user.js.erb.hooks", "w" do |f|
         f.puts File.read("glob/application.js")
         f.puts File.read("glob/user_compiler.js")
         f.puts File.read("glob/services.js")
         f.puts File.read("glob/scripts.js")
       end
 
-      #8. The `erb` files is then sent to `./products/$PLATFORM/glob/application_user.js` with the below `ERB` variables allowable.
+      #9. The `hooks` compiler then runs over the source injecting any necessary hook code into the special comments by going through `./config/hooks.rb` in the user's project.
+      erb_hooks_src = File.read "glob/application_user.js.erb.hooks"
+      manifest = Flok::UserHooksToManifestOrchestrator.convert_hooks_to_manifest File.read("#{user_project_dir}/config/hooks.rb")
+      erb_src = Flok::HooksCompiler.compile erb_hooks_src, manifest
+      File.write "glob/application_user.js.erb", erb_src
+
+      #9. The `erb` files is then sent to `./products/$PLATFORM/glob/application_user.js` with the below `ERB` variables allowable.
       erb_src = File.read "glob/application_user.js.erb"
       renderr = ERB.new(erb_src)
       context = ERBUserApplicationContext.new()

data/docs/compilation.md

@@ -18,7 +18,7 @@ as necessary.*
  6. All js files are globbed from `./products/$PLATFORM/glob` and combined into `./products/$PLATFORM/glob/application.js.erb`
  7. Auto-generated code is placed at the end (like PLATFORM global)
  8. The module specific code in `./kern/mod/.*js` are added when the name of the file (without the js part) is mentioned in the `./app/drivers/$PLATFORM/config.yml` `mods` section and appended to `glob/application.js.erb`
- 9. The compiled `glob/application.js.erb` file is run through the ERB compiler and formed into `application.js`
+ 9. The compiled `glob/application.js.erb` file is run through the ERB compiler and formed into `application.js`. This adds things like static debug variables, and hooks.
 
 ##Erb variables
 All kernel source files support embedded ERB code like `<% if DEBUG %>Code<% end %>`. These files include:

data/docs/kernel_api.md

@@ -27,7 +27,7 @@ instead.
   * `gen_id()` - Will return a random unique id (8 character string).
 
 ##Events
-  * `reg_evt(ep, f)` - Register a function to be called when an event is processed by `int_event`. The function will receive `(ep, event_name, info)`.
+  * `reg_evt(ep, f)` - Register a function to be called when an event is processed by `int_event`. The function will receive `(ep, event_name, info)`. ep must be either a string or number.
 
   * `dereg_evt(ep)` - Do not do anything if ep is received as an `int_event`
 

data/docs/kernel_handbook/hooks.md

@@ -0,0 +1,4 @@
+# Hooks in the kernel
+
+## How user-generators work
+As mentioned in the [User Handbook | Hooks](../user_handbook/hooks.md), user-generators are compiled into the kernel when the 

data/docs/mod/dlink.md

@@ -0,0 +1,18 @@
+#Deep Link Module (dlink)
+The deep linking module allows your application to support start-up URL requests. Many mobile operating systems allow apps to intercept certain URL namespaces which force redirection to an app instead of the default behaviour of a web-browser. This URL on startup feature allows the app to dynamically respond to a URL request from an outside source.
+
+#### Kernel
+`int_dlink_notify(url, params)` - An inbound deep-link was intercepted and forwarded. The params are a javascript dictionary of the link parameters and
+the url is the base url of the link.  E.g. if the link was `http://google.com/test?my_param=foo` then the url would be `http://google.com/test` and the
+`params` are `{my_param: foo}`. This function simple calls the `dlink_notify_handler(url, params)` with the same
+parameters. This handler function is currently only ownedowned by the sister-service `dlink`. In the future, we would
+like to support the full RFC specification for URI's, but at this time, all the URI libraries are too large to warrant adding the additional bloat especially when
+most clients have native ways of decoding URI's.
+
+#### Kernel Spec Interrupts
+`get_int_dlink_spec()` - Sends [[0, 1, "get_int_dlink_cb_spec", [url, params]] with the last received request from `int_dlink_notify`.
+
+#### Driver
+There is no requests the driver must handle. However, the driver should dispatch the message for the `int_dlink_notify` off the main queue. It should never be dispatched
+before the application has fully started up. It is internally asynchronously dispatched, but for safety's sake, it should be dispatched at the soonest, immediately after
+the system has loaded.

data/docs/mod/hook.md

@@ -0,0 +1,9 @@
+#Hook
+The hook module allows the client to receive hook_event messages. This is a required module.
+
+###Driver messages
+`if_hook_event(name, info)` - The name of the hook event and the information received.
+
+####Driver spec functions (only required in debug mode)
+`if_hook_spec_dump_rcvd_events` - Schedules the event `if_hook_spec_dump_res` to be sent out with a message in the form of `[1, "if_hook_spec_dump_rcvd_events_res", [{name:name, info:info}, ...]}` where the array contains
+the parameters to all the calls to `if_hook_event` with the example hash and in sequential order where the oldest is the greatest index.

data/docs/project.md

@@ -35,8 +35,9 @@ You create and build projects via the `flok` command. You must set the `$FLOK_EN
   5. The service configuration in `./config/services.rb` is read and run through `services_compiler` and files from
   `./products/$PLATFORM/services/combined_services.rb`. The output of this file is moved to `./products/$PLATFORM/glob/services.js`
   6. `./products/$PLATFORM/application.js` is moved to `./products/$PLATFORM/glob/application.js`
-  7. The local project `./products/$PLATFORM/glob/application.js` and `./products/$PLATFORM/glob/user_compiler.js` and `./products/$PLATFORM/glob/services.js` and `./products/$PLATFORM/glob/scripts.js`  are merged into `./products/$PLATFORM/glob/application_user.js.erb`.
-  8. The `erb` files is then sent to `./products/$PLATFORM/glob/application_user.js` with the below `ERB` variables allowable.
+  7. The local project `./products/$PLATFORM/glob/application.js` and `./products/$PLATFORM/glob/user_compiler.js` and `./products/$PLATFORM/glob/services.js` and `./products/$PLATFORM/glob/scripts.js`  are merged into `./products/$PLATFORM/glob/application_user.js.erb.hooks`.
+  9. The `hooks` compiler then runs over the source injecting any necessary hook code into the special comments by going through `./config/hooks.rb` in the user's project. This file is saved to  `./products/$PLATFORM/glob/application_user.js.erb` 
+  10. The `erb` files is then sent to `./products/$PLATFORM/glob/application_user.js` with the below `ERB` variables allowable.
 
 ####Supported variables
   * `@debug` - Set to `true` when FLOK_ENV=DEBUG

data/docs/services/dlink.md

@@ -0,0 +1,8 @@
+#dlink - Deep Link Service
+The **deep_link** service requires the `dlink` module to function. It implements the function `dlink_notify_handler` which is called by the `dlink` 
+module. All controllers that include this service will receive the `dlink_req` event with the parameters `{url: url, params: params}` via a
+asynchronous event. An example of the `url` and `params` in `http://google.com/test?foo=bar` would be `{url: "http://google.com/test", {foo: "bar"}}`
+
+##Spec behaviours
+When a request is made to the `dlink` port, see the `dlink` module for the port, any controllers registered to
+this service should receive the `dlink:reqeust` with the appropriate parameters

data/docs/user_handbook/hooks.md

@@ -0,0 +1,106 @@
+#Hooks (User Guide)
+
+## What problems do hooks solve?
+##### There are two questions that *Hooks* were designed to solve.
+
+1. Animation segues.  When a controller switches actions, often time it is swapping out view controllers. Adding animations at this time would be the optimal time to do so.  However, different clients, take blackberry and iOS, may either have fully-automated-animations, gesture controlled animations, cancelable-animations, synchronous-blocking, and the list goes on-and-on. Clearly, animations are handled differently on each platform, so how do we allow each platform to manage animation-segues?
+2. There are times when a client, e.g. chrome, need to support semantics that are platform dependent.  *For example*, you may need the back button in your web client to trigger a view controller to go back a page. However, this semantic does not make much sense when you have multiple view controllers; e.g. What view controller receives the back clicked event?
+
+##### Additionally, these questions must be solved with these constraints
+1. Allowing the client to choose interception points at runtime would be prohibitively slow.  Therefore, care should be taken to make sure hooks are as static as possible and do not add un-necessary runtime overhead.
+
+-------
+
+##### How hooks solves these problems:
+*Hooks* solves these questions and constraitns by allowing the user to define triggers in their project under `./config/hooks.rb` using a *DSL* which in-turn notifies the client. The client then handles each hook in an appropriate fashion.
+
+## Hooking by example with `./config/hooks.rb`
+
+**Here is an example of a `./config/hooks.rb` which tells flok to notify the client that the `supports_back_clicked` hook triggered whenever a controller instance of a `"my_controller"` controller switches to an action via Goto that has an event handler defined with `back_clicked`:**
+
+```ruby
+# $USER_POJECT_ROOT/config/hooks.rb
+hook :goto => :supports_back_clicked do
+  #Selectors (Each selector reduces the toal search area, if you have no selectors, it's like SELECT *)
+  to_action_responds_to? "back_clicked"
+  controller_name "my_controller"
+  
+  #Configuration methods
+  is_sync
+end
+```
+
+**The basic format of each hook looks like:**
+```ruby
+hook :hook_generator_name => :hook_notification_name do
+  #Selector methods & Configuration specific to the hook generator
+end
+```
+
+Selectors for each hook generator create more specific requirements for a trigger. By convention, all hook generators, if supplied no selector arguments will select all possible.  **For example, this would hook all Goto statements in all controllers**:
+```ruby
+hook :hook_generator_name => :hook_notification_name do
+end
+```
+
+## Handling hook notifications in the client
+---
+The client, in-turn must handle the hook notification, in this example, the hook notification is named `supports_back_clicked`. The hook notifications typically includes a set of parameters, but the parameters are dependent on the *hook generator* used.  In the above example, we are using the `goto` hook generator. See below for the different `hook generators` specifics.
+
+** See client docs for how to handle hook notifications, here is an example in pseudo code: **
+```ruby
+handleHook("supports_back_clicked", function(hookInfo) {
+  var to_action_name = hookInfo.to_action_name;
+});
+```
+
+## Hook generators
+
+  * `goto` - Intercept `Goto` transitions and when a controller first loads (by virtue that a controller runs `Goto` when it first is initialized)
+    * `DSL Selectors`
+      * `to_action_responds_to? "event_name"` - Whenever a controller switches **to** an action that contains an `on "event_name", %{...}` handler
+      * `from_action_responds_to? "event_name"` - Whenever a controller switches **from** an action that contains an `on "event_name", %{...}` handler
+      * `controller "controller_name"` - Only applies to controllers with the name `"controller_name"`
+
+## How the hook generators are defined & hooking internals
+See [Kernel Handbook | Hooks](../kernel_handbook/hooks.md)
+
+##How hooks are compiled into the kernel
+The user's `./config/hooks.rb` file is compiled and then evaluated statically to get a listing of all the controllers that the hooks can apply to. Then the compiler goes over each controller
+and inserts code at particular hook detection points; the nature of the insertions is up to the particular hooking context.
+
+##Synchronous vs Asynchronous Hooks
+Whether a hook is synchronous or not synchronous depends entirely on the type of hook in question. An example of a possible synchronous hook is a hook jkkkkkkkkkk..j
+
+##Hooking check points
+Each controller has a plethora of functions that determine it's lifetime and behaviours. These functions include the actions of creation, destruction, embedding, pushing actions, talking to services, etc.
+These functions are built into the ctable entry for each controller and possible controller related functions like _embed. Each controller entry point is marked with a special comment marker that has
+the following JSON format:
+
+```ruby 
+//HOOK_ENTRY[my_name] {foo: "bar"}...
+```
+The name is the hook name and the params is context specific inforamtion the compiler has embedded. Live variables that are in the context of the hook detection point are described in each hook detection point below.
+
+  * `controller_will_goto` - The controller is about to invoke the Goto macro and switch actions or it has just entered the first action from choose_action (which is a Goto).
+    * params (static generated)
+      * `controller_name` - The controller name that this entry effects
+      * `from_action` - The name of the action we are coming from
+      * `to_action` - The name of the action we are going to
+    * Useful (dynamic) variables
+      * `old_action` - The previous action, equal to `from_action` but in dynamic form. If there is no action, this is set to `choose_action`. Not sure why you would use this
+      * `__info__.action` - The name of the new action
+  * `${controller_name}_did_destroy` - The controller has *just* been destroyed
+
+##Hooks Compiler
+The hooks compiler is able to take the hook entry points and inject code into them via a set of `HooksManifestEntries` which are bound togeather via a `HooksManifest`. The actual
+compiler only takes the original source code, the `HooksManifest` and then spits out a version that no longer contains the special hook entry comments and contains any
+injected hooking code.
+
+
+##User Hook Generators
+
+###./config/hooks.rb
+The hooks configuration file contains the user's DSL hooks. This file is not compiled directly by `HooksManifest` but rather many intermediate `UserHookGenerator` are
+used to parse the `./config/hooks.rb` and this conversion is orchestrated by the singleton `UserHooksToManifestOrchestrator`. Each `UserHook` is defined in the `./lib/user_hook_generators.rb`
+and are never meant to directly be created by users.