joosy 0.1.0.RC2 → 0.1.0.RC3

data/app/assets/javascripts/joosy/core/router.js.coffee

@@ -1,23 +1,77 @@
 #= require joosy/core/joosy
 
+#
+# Router. Reacts on a hash change event and loads proper pages
+#
+# Example:
+#   Joosy.Router.map
+#     404             : (path) -> alert "Page '#{path}' was not found :("
+#     '/'             : Welcome.IndexPage
+#     '/resources'    :
+#     '/'           : Resource.IndexPage
+#     '/:id'        : Resource.ShowPage
+#     '/:id/edit'   : Resource.EditPage
+#     '/new'        : Resource.EditPage
+#
+# @module
+#
 Joosy.Router =
+  #
+  # The Object containing route parts in keys and pages/lambdas in values
+  #
   rawRoutes: Object.extended()
+  
+  #
+  # Flattern routes mapped to regexps (to check if current route is what we 
+  # need) and actual executors
+  #
   routes: Object.extended()
 
+  #
+  # Clears the routes
+  #
   reset: ->
     @rawRoutes = Object.extended()
     @routes = Object.extended()
 
+  #
+  # Registers the set of raw routes
+  # This method will only store routes and will not make them act immediately
+  # Routes get registered only once at system initialization during #__setupRoutes call
+  #
+  # @param [Object] routes        Set of routes in inner format (see class description)
+  #
   map: (routes) ->
     Joosy.Module.merge @rawRoutes, routes
 
-  setupRoutes: ->
-    @prepareRoutes @rawRoutes
-    @respondRoute location.hash
-    $(window).hashchange =>
-      @respondRoute location.hash
+  #
+  # Changes current hash with shebang (#!) and therefore triggers new route loading
+  # to be loaded
+  #
+  # @param [String] to            Route to navigate to
+  #
+  navigate: (to) ->
+    location.hash = '!' + to
 
-  prepareRoutes: (routes, namespace='') ->
+  #
+  # Inits the routing system and loads the current route
+  # Binds the window hashchange event and therefore should only be called once
+  # during system startup
+  #
+  __setupRoutes: ->
+    @__prepareRoutes @rawRoutes
+    @__respondRoute location.hash
+    $(window).hashchange =>
+      @__respondRoute location.hash
+
+  #
+  # Compiles routes to map object
+  # Object will contain regexp string as key and lambda/Page to load as value
+  #
+  # @param [Object] routes        Raw routes to prepare
+  # @param [String] namespace     Inner cursor for recursion
+  #
+  __prepareRoutes: (routes, namespace='') ->
     if !namespace && routes[404]
       @wildcardAction = routes[404]
       delete routes[404]
@@ -25,11 +79,18 @@ Joosy.Router =
     Object.each routes, (path, response) =>
       path = (namespace + path).replace /\/{2,}/, '/'
       if response && (Object.isFunction(response) || response.prototype?)
-        Joosy.Module.merge @routes, @prepareRoute(path, response)
+        Joosy.Module.merge @routes, @__prepareRoute(path, response)
       else
-        @prepareRoutes response, path
-
-  prepareRoute: (path, response) ->
+        @__prepareRoutes response, path
+
+  #
+  # Compiles one single route
+  #
+  # @param [String] path            Full path from raw route
+  # @param [Joosy.Page] response    Page that should be loaded at this route 
+  # @param [Function] response      Lambda to call at this route
+  #
+  __prepareRoute: (path, response) ->
     matchPath = path.replace(/\/:([^\/]+)/g, '/([^/]+)').replace(/^\/?/, '^/?').replace(/\/?$/, '/?$')
     result    = Object.extended()
 
@@ -39,18 +100,23 @@ Joosy.Router =
       action: response
     result
 
-  respondRoute: (hash) ->
+  #
+  # Searches the corresponding route through compiled routes
+  #
+  # @param [String] hash        Hash value to search route for
+  #
+  __respondRoute: (hash) ->
     Joosy.Modules.Log.debug "Router> Answering '#{hash}'"
     fullPath = hash.replace /^#!?/, ''
     @currentPath = fullPath
     found = false
     queryArray = fullPath.split '&'
     path       = queryArray.shift()
-    urlParams  = @paramsFromQueryArray queryArray
+    urlParams  = @__paramsFromQueryArray queryArray
 
     for regex, route of @routes when @routes.hasOwnProperty regex
       if vals = path.match new RegExp(regex)
-        params = @paramsFromRouteMatch(vals, route).merge urlParams
+        params = @__paramsFromRouteMatch(vals, route).merge urlParams
 
         if Joosy.Module.hasAncestor route.action, Joosy.Page
           Joosy.Application.setCurrentPage route.action, params
@@ -63,7 +129,14 @@ Joosy.Router =
     if !found && @wildcardAction?
       @wildcardAction path, urlParams
 
-  paramsFromRouteMatch: (vals, route) ->
+  #
+  # Collects params from route placeholders (/foo/:placeholder)
+  #
+  # @param [Array] vals         Array of value gathered by regexp
+  # @param [Object] route       Compiled route
+  # @returns [Object]           Hash of params
+  #
+  __paramsFromRouteMatch: (vals, route) ->
     params = Object.extended()
 
     vals.shift()
@@ -72,7 +145,13 @@ Joosy.Router =
 
     params
 
-  paramsFromQueryArray: (queryArray) ->
+  #
+  # Collects params from query routes (/foo/&a=b)
+  #
+  # @param [Array] queryArray   Array of query string split by '&' sign
+  # @returns [Object]           Hash of params
+  #
+  __paramsFromQueryArray: (queryArray) ->
     params = Object.extended()
 
     if queryArray
@@ -81,7 +160,4 @@ Joosy.Router =
           pair = @split '='
           params[pair[0]] = pair[1]
 
-    params
-
-  navigate: (to) ->
-    location.hash = '!' + to
+    params

data/app/assets/javascripts/joosy/core/widget.js.coffee

@@ -6,6 +6,15 @@
 #= require joosy/core/modules/renderer
 #= require joosy/core/modules/filters
 
+#
+# Base class for all of your Joosy Layouts.
+#
+# @todo Add link to the 5th chapter of guides here.
+#
+# @example Sample widget
+#   class @FooWidget extends Joosy.Widget
+#     @view 'foo'
+#
 class Joosy.Widget extends Joosy.Module
   @include Joosy.Modules.Log
   @include Joosy.Modules.Events
@@ -14,16 +23,41 @@ class Joosy.Widget extends Joosy.Module
   @include Joosy.Modules.Filters
   @include Joosy.Modules.TimeManager
 
+  #
+  # By default widget will not render on load
+  #
   __renderer: false
-  
+
+  #
+  # Initial data that will be passed to view on load
+  # False (and not {}) by default to have a chance to check if data was loaded
+  #
   data: false
 
+  #
+  # Proxy to Joosy.Router#navigate
+  #
   navigate: (args...) ->
     Joosy.Router.navigate args...
 
+  #
+  # This is required by {Joosy.Modules.Renderer}
+  # Sets the base template dir to app_name/templates/widgets
+  #
   __renderSection: ->
     'widgets'
 
+  #
+  # Widget bootstrap proccess
+  #
+  #   * Rendering (if required)
+  #   * {Joosy.Modules.Container#refreshElements}
+  #   * {Joosy.Modules.Container#__delegateEvents}
+  #   * {Joosy.Modules.Filters#__runAfterLoads}
+  #
+  # @param [Joosy.Page, Joosy.Layout]     Page or Layout to attach to
+  # @param [jQuery] container             Container to attach to
+  #
   __load: (@parent, @container) ->
     if @__renderer
       @container.html @__renderer(@data || {})
@@ -33,6 +67,13 @@ class Joosy.Widget extends Joosy.Module
 
     this
 
+  #
+  # Layout destruction proccess.
+  #
+  #   * {Joosy.Modules.TimeManager#__clearTime}
+  #   * {Joosy.Modules.Renderer#__removeMetamorphs}
+  #   * {Joosy.Modules.Filters#__runAfterUnloads}
+  #
   __unload: ->
     @__clearTime()
     @__removeMetamorphs()

data/app/assets/javascripts/joosy/preloaders/caching.js.coffee

@@ -1,18 +1,20 @@
-#= require base64
-
 #
 # Preloader for libraries with localStorage cache
 #
-# Example:
+# @note The `start` callback will only be called if loading required. 
+#   While working with cache, `complete` is the only callback that will be triggered.
+#
+# @example Basic usage
 #   libraries = [['/test1.js', 100], ['/test2.js', 500]] #100, 500 - size in bytes
+#   
 #   CachingPreloader.load libraries,
 #     start:    -> console.log 'preloading started'
 #     progress: (percent) -> console.log "#{percent}% loaded"
 #     complete: -> console.log 'preloading finished'
 #
-# @class CachingPreloader
+# @module
 #
-@Preloader = @CachingPreloader =
+@CachingPreloader =
   #
   # If set to true, localStorage cache will be avoided
   #
@@ -50,6 +52,7 @@
       @restore()
     else
       @start?.call window
+      @clean()
       @download libraries
 
   #
@@ -60,16 +63,21 @@
     for name, i in @libraries
       flag &&= window.localStorage.getItem(name)?
     flag
-  
+
+  #
+  # Escapes non-printable terminal chars before storing to localStorage to prevent IE bug
+  #
+  # @param [String] String, that will be prepared for localStorage
+  #
+  escapeStr: (str) ->
+    str.replace(new RegExp("\u0001", 'g'), "\\u0001").replace(new RegExp("\u000B", 'g'), "\\u000B")
+
   #
   # Gets sources of scripts from localStorage and evals them
   #
   restore: ->
     for name, i in @libraries
-      code = window.localStorage.getItem name
-      if window.navigator.appName == "Microsoft Internet Explorer"
-        code = Base64.decode code
-      @evalGlobaly code
+      window.evalGlobaly window.localStorage.getItem name
     @complete?.call window, true
 
   #
@@ -89,12 +97,11 @@
       @ajax url, size, (xhr) =>
         code = xhr.responseText
         if window.navigator.appName == "Microsoft Internet Explorer"
-          code = Base64.encode code
+          code = @escapeStr code
         window.localStorage.setItem @prefix+url, code
-        @evalGlobaly xhr.responseText
+        window.evalGlobaly xhr.responseText
         @download libraries
     else
-      @clean()
       @complete?.call window
 
   #
@@ -135,20 +142,28 @@
   #
   clean: ->
     i = 0
+    
+    find = (arr, obj) ->
+      (return i if obj == x) for x in arr
+      return -1
 
     while i < window.localStorage.length && key = window.localStorage.key(i)
-      if key.indexOf(@prefix) == 0 && @libraries.indexOf(key) < 0
+      if key.indexOf(@prefix) == 0 && find(@libraries, key) < 0
         window.localStorage.removeItem key
       else
         i += 1
 
-  #
-  # Evals source at a global scope
-  #
-  # @param [String] JS source to execute
-  #
-  evalGlobaly: (src) ->
-    if window.execScript
-      window.execScript src
-    else
-      window.eval src
+#
+# Evals source at a global scope
+# Don't touch it! It should be window's property, or FF3.6 will execute scripts on preloader context.
+#
+# @param [String] JS source to execute
+#
+window.evalGlobaly = (src) ->
+  return if src.length == 0
+  if window.execScript
+    window.execScript src
+  else
+    window.eval src
+
+@Preloader = @CachingPreloader

data/app/assets/javascripts/joosy/preloaders/inline.js.coffee

@@ -1,18 +1,18 @@
 #
-# Preloader for libraries using <script src> without any caching magic
+# Preloader for libraries using `script src` without any caching magic
 #
-# Example:
+# @example Basic usage
 #   libraries = [['/test1.js'], ['/test2.js']]
+#   
 #   InlinePreloader.load libraries,
 #     start:    -> console.log 'preloading started'
 #     complete: -> console.log 'preloading finished'
 #
-# @class InlinePreloader
+# @module
 #
-@Preloader = @InlinePreloader =
-
+@InlinePreloader =
   #
-  # Loads set of libraries by adding <script src> to DOM head 
+  # Loads set of libraries by adding `script src` to DOM head 
   # See class description for example of usage
   #
   # @param [Array] 2-levels array of libraries URLs i.e. [['/test1.js'],['/test2.js']]
@@ -30,7 +30,7 @@
       @complete?()
 
   #
-  # Loads one script by adding <script src> to DOM head
+  # Loads one script by adding `script src` to DOM head
   #
   # @param [String] url to load script from
   # @param [Function] `() -> null` to call after script was loaded and executed
@@ -52,3 +52,5 @@
 
     head.appendChild script
     return undefined
+
+@Preloader = @InlinePreloader

data/app/helpers/joosy/sprockets_helper.rb

@@ -1,10 +1,13 @@
+require 'uri'
+
 module Joosy::SprocketsHelper
   def extract_sources_and_sizes_from_include_tag(name)
     code = javascript_include_tag name
     resources = code.scan(/(?:href|src)=['"]([^'"]+)['"]/).flatten
 
     resources.map do |resource|
-      path = ::Rails.root.to_s + "/public" + resource.split('?')[0]
+      uri  = URI.parse resource
+      path = ::Rails.root.to_s + "/public" + uri.path
       size = File.size(path) rescue false
       [resource, size]
     end.to_json.html_safe

data/lib/joosy/rails/version.rb

@@ -1,5 +1,5 @@
 module Joosy
   module Rails
-    VERSION = "0.1.0.RC2"
+    VERSION = "0.1.0.RC3"
   end
 end

data/spec/javascripts/joosy/core/application_spec.js.coffee

@@ -1,11 +1,11 @@
 describe "Joosy.Application", ->
 
   beforeEach ->
-    sinon.stub(Joosy.Router, "setupRoutes")
+    sinon.stub(Joosy.Router, "__setupRoutes")
     @seedGround()
 
   afterEach ->
-    Joosy.Router.setupRoutes.restore()
+    Joosy.Router.__setupRoutes.restore()
 
   it "should initialize", ->
     Joosy.Application.initialize 'app', '#application'
@@ -13,7 +13,7 @@ describe "Joosy.Application", ->
     expect(Joosy.Application.selector).toEqual '#application'
     expect(Joosy.Application.sandboxSelector).toMatch /#[0-9A-F]{8}-[0-9A-F]{4}-4[0-9A-F]{3}-[0-9A-F]{4}-[0-9A-F]{12}/
     expect($(Joosy.Application.sandboxSelector).length).toEqual 1
-    expect(Joosy.Router.setupRoutes.callCount).toEqual 1
+    expect(Joosy.Router.__setupRoutes.callCount).toEqual 1
     expect(Joosy.Application.name).toEqual 'app'
 
   it "should set container", ->

data/spec/javascripts/joosy/core/resource/rest_spec.js.coffee

@@ -19,8 +19,6 @@ describe "Joosy.Resource.REST", ->
     expect(@Test.__buildSource()).toEqual 'uri/'
     @Test.primary 'uid'
     expect(@Test::__primaryKey).toEqual 'uid'
-    @Test.beforeLoad 'function'
-    expect(@Test::__beforeLoad).toEqual 'function'
 
   it "should build source url based on entity name", ->
     options =

data/spec/javascripts/joosy/core/router_spec.js.coffee

@@ -26,20 +26,20 @@ describe "Joosy.Router", ->
     expect(Joosy.Router.rawRoutes).toEqual map
 
   it "should initialize on setup", ->
-    sinon.stub Joosy.Router, 'prepareRoutes'
-    sinon.stub Joosy.Router, 'respondRoute'
+    sinon.stub Joosy.Router, '__prepareRoutes'
+    sinon.stub Joosy.Router, '__respondRoute'
 
     Joosy.Router.map map
-    Joosy.Router.setupRoutes()
-    expect(Joosy.Router.prepareRoutes.callCount).toEqual 1
-    expect(Joosy.Router.prepareRoutes.args[0][0]).toEqual map
-    expect(Joosy.Router.respondRoute.callCount).toEqual 1
-    expect(Joosy.Router.respondRoute.args[0][0]).toEqual location.hash
-    Joosy.Router.prepareRoutes.restore()
-    Joosy.Router.respondRoute.restore()
+    Joosy.Router.__setupRoutes()
+    expect(Joosy.Router.__prepareRoutes.callCount).toEqual 1
+    expect(Joosy.Router.__prepareRoutes.args[0][0]).toEqual map
+    expect(Joosy.Router.__respondRoute.callCount).toEqual 1
+    expect(Joosy.Router.__respondRoute.args[0][0]).toEqual location.hash
+    Joosy.Router.__prepareRoutes.restore()
+    Joosy.Router.__respondRoute.restore()
 
   it "should prepare route", ->
-    route = Joosy.Router.prepareRoute "/such/a/long/long/url/:with/:plenty/:of/:params", "123"
+    route = Joosy.Router.__prepareRoute "/such/a/long/long/url/:with/:plenty/:of/:params", "123"
 
     expect(route).toEqual Object.extended
       '^/?such/a/long/long/url/([^/]+)/([^/]+)/([^/]+)/([^/]+)/?$':
@@ -47,10 +47,10 @@ describe "Joosy.Router", ->
         action: "123"
 
   it "should cook routes", ->
-    sinon.stub Joosy.Router, 'respondRoute'
+    sinon.stub Joosy.Router, '__respondRoute'
 
     Joosy.Router.map map
-    Joosy.Router.setupRoutes()
+    Joosy.Router.__setupRoutes()
 
     expect(Joosy.Router.routes).toEqual Object.extended
       '^/?/?$':
@@ -66,11 +66,11 @@ describe "Joosy.Router", ->
         capture: ['more']
         action: TestPage
 
-    Joosy.Router.respondRoute.restore()
+    Joosy.Router.__respondRoute.restore()
 
   it "should get route params", ->
-    route  = Joosy.Router.prepareRoute "/such/a/long/long/url/:with/:plenty/:of/:params", "123"
-    result = Joosy.Router.paramsFromRouteMatch ['full regex match here', 1, 2, 3, 4], route.values().first()
+    route  = Joosy.Router.__prepareRoute "/such/a/long/long/url/:with/:plenty/:of/:params", "123"
+    result = Joosy.Router.__paramsFromRouteMatch ['full regex match here', 1, 2, 3, 4], route.values().first()
 
     expect(result).toEqual Object.extended
       'with':   1
@@ -79,37 +79,37 @@ describe "Joosy.Router", ->
       'params': 4
 
   it "should build query params", ->
-    result = Joosy.Router.paramsFromQueryArray ["foo=bar", "bar=baz"]
+    result = Joosy.Router.__paramsFromQueryArray ["foo=bar", "bar=baz"]
 
     expect(result).toEqual Object.extended
       foo: 'bar'
       bar: 'baz'
 
   it "should respond routes", ->
-    sinon.stub Joosy.Router, 'respondRoute'
+    sinon.stub Joosy.Router, '__respondRoute'
     sinon.stub Joosy.Application, 'setCurrentPage'
 
     Joosy.Router.map map
-    Joosy.Router.setupRoutes()
+    Joosy.Router.__setupRoutes()
 
-    Joosy.Router.respondRoute.restore()
+    Joosy.Router.__respondRoute.restore()
 
-    Joosy.Router.respondRoute '/'
+    Joosy.Router.__respondRoute '/'
     expect(spies.root.callCount).toEqual 1
 
-    Joosy.Router.respondRoute '/page'
+    Joosy.Router.__respondRoute '/page'
     expect(Joosy.Application.setCurrentPage.callCount).toEqual 1
     expect(Joosy.Application.setCurrentPage.args.last()).toEqual [TestPage, Object.extended()]
 
-    Joosy.Router.respondRoute '/section/page/1'
+    Joosy.Router.__respondRoute '/section/page/1'
     expect(spies.section.callCount).toEqual 1
     expect(spies.section.args.last()).toEqual [Object.extended(id: '1')]
 
-    Joosy.Router.respondRoute '/section/page2/1&a=b'
+    Joosy.Router.__respondRoute '/section/page2/1&a=b'
     expect(Joosy.Application.setCurrentPage.callCount).toEqual 2
     expect(Joosy.Application.setCurrentPage.args.last()).toEqual [TestPage, Object.extended(more: '1', a: 'b')]
 
-    Joosy.Router.respondRoute '/thiswillneverbefound&a=b'
+    Joosy.Router.__respondRoute '/thiswillneverbefound&a=b'
     expect(spies.wildcard.callCount).toEqual 1
     expect(spies.wildcard.args.last()).toEqual ['/thiswillneverbefound', Object.extended(a: 'b')]