joosy 0.1.0.RC2 → 0.1.0.RC3

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

@@ -8,6 +8,14 @@
 #= require joosy/core/modules/widgets_manager
 #= require joosy/core/modules/filters
 
+#
+# Base class for all of your Joosy Layouts.
+# @see http://guides.joosy.ws/guides/layouts-pages-and-routing.html
+#
+# @example Sample application layout
+#   class @ApplicationLayout extends Joosy.Layout
+#     @view 'application'
+#
 class Joosy.Layout extends Joosy.Module
   @include Joosy.Modules.Log
   @include Joosy.Modules.Events
@@ -19,39 +27,136 @@ class Joosy.Layout extends Joosy.Module
 
   @view 'default'
 
+  #
+  # Sets the method which will controll the painting preparation proccess.
+  #
+  # This method will be called right ater previous layout {Joosy.Layout.erase} and in parallel with
+  #   layout data fetching so you can use it to initiate preloader.
+  #
+  # @note Given method will be called with `complete` function as parameter. As soon as your
+  #   preparations are done you should call that function.
+  #
+  # @example Sample before painter
+  #   @beforePaint (complete) ->
+  #     if !@data # checks if parallel fetching finished
+  #       $('preloader').slideDown -> complete()
+  # 
+  #
   @beforePaint: (callback) ->
     @::__beforePaint = callback
+    
+  #
+  # Sets the method which will controll the painting proccess.
+  #
+  # This method will be called after fetching, erasing and beforePaint is complete.
+  # It should be used to setup appearance effects of layout.
+  #
+  # @note Given method will be called with `complete` function as parameter. As soon as your
+  #   preparations are done you should call that function.
+  #
+  # @example Sample painter
+  #   @paint (complete) ->
+  #     @container.fadeIn -> complete()
+  #
   @paint: (callback) ->
     @::__paint = callback
+
+  #
+  # Sets the method which will controll the erasing proccess.
+  #
+  # Use this method to setup hiding effect.
+  #
+  # @note Given method will be called with `complete` function as parameter. As soon as your
+  #   preparations are done you should call that function.
+  #
+  # @note This method will be caled _before_ unload routines so in theory you can
+  #   access layout data from that. Think twice if you are doing it right though.
+  #
+  # @example Sample eraser
+  #   @erase (complete) ->
+  #     @container.fadeOut -> complete()
+  #
   @erase: (callback) ->
     @::__erase = callback
-    
+  
+  #
+  # Sets the method which will controll the data fetching proccess.
+  #
+  # @note Given method will be called with `complete` function as parameter. As soon as your
+  #   preparations are done you should call that function.
+  #
+  # @note You are strongly encouraged to NOT fetch anything with Layout!
+  #   Use {Joosy.Page.fetch}
+  #
+  # @example Basic usage
+  #   @fetch (complete) ->
+  #     $.get '/rumbas', (@data) => complete()
+  #
   @fetch: (callback) ->
     @::__fetch = callback
 
+  #
+  # Defaults to `false` to ease beforePaint state check.
+  #
   data: false
   
+  #
+  # @param [Hash] params              List of route params
+  #
   constructor: (@params) ->
 
+  #
+  # @see 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/layouts
+  #
   __renderSection: ->
     'layouts'
 
+  #
+  # Layout bootstrap proccess.
+  #
+  #   * {Joosy.Modules.Container#refreshElements}
+  #   * {Joosy.Modules.Container#__delegateEvents}
+  #   * {Joosy.Modules.WidgetsManager#__setupWidgets}
+  #   * {Joosy.Modules.Filters#__runAfterLoads}
+  #
   __load: (@container) ->
     @refreshElements()
     @__delegateEvents()
     @__setupWidgets()
     @__runAfterLoads()
 
+  #
+  # Layout destruction proccess.
+  #
+  #   * {Joosy.Modules.TimeManager#__clearTime}
+  #   * {Joosy.Modules.WidgetsManager#__unloadWidgets}
+  #   * {Joosy.Modules.Renderer#__removeMetamorphs}
+  #   * {Joosy.Modules.Filters#__runAfterUnloads}
+  #
   __unload: ->
     @__clearTime()
     @__unloadWidgets()
+    @__removeMetamorphs()
     @__runAfterUnloads()
 
+  #
+  # @todo Rename this shit already. We are not going to release having function that marks
+  #   element with UUID called `yield`.
+  #
   yield: ->
     @uuid = Joosy.uuid()
 
+  #
+  # Gets layout element.
+  #
+  # @return [jQuery]
+  #
   content: ->
     $("##{@uuid}")

data/app/assets/javascripts/joosy/core/modules/container.js.coffee

@@ -1,3 +1,10 @@
+#
+# DOM container handling, DOM elements and DOM events bindings
+#
+# @note Requires implementor to contain DOM node at @container propert
+#
+# @module
+#
 Joosy.Modules.Container =
   events: false
   elements: false
@@ -7,16 +14,33 @@ Joosy.Modules.Container =
   $: (selector) ->
     $(selector, @container)
 
+  #
+  # Rebinds selectors defined in 'elements' hash to object properties
+  #
+  # @example Sample elements
+  #   elements:
+  #     foo: '.foo'
+  #     bar: '.bar'
+  #
   refreshElements: ->
     @__collectElements().each (key, value) =>
       # TODO: Check for possible collisions?
       @[key] = @$(value)
 
+  #
+  # Fills container with given data removing all events
+  #
+  # @param [jQuery] container       jQuery entity of container to update
+  # @param [String] data            HTML to inject
+  #
   swapContainer: (container, data) ->
     container.unbind().off()
     container.html data
     container
 
+  #
+  # Gathers 'elements' from current and super classes
+  #
   __collectElements: ->
     elements = Object.extended @elements || {}
 
@@ -26,6 +50,9 @@ Joosy.Modules.Container =
 
     elements
 
+  #
+  # Gathers 'events' from current and super classes
+  #
   __collectEvents: ->
     events = Object.extended @events || {}
 
@@ -35,12 +62,26 @@ Joosy.Modules.Container =
 
     events
 
+  #
+  # Converts '$...' notation to selector from 'elements'
+  #
+  # @param [String] selector            Selector to convert
+  #
   __extractSelector: (selector) ->
     if r = selector.match /\$([A-z]+)/
       selector = @__collectElements()[r[1]]
 
     selector
 
+  #
+  # Bings events defined in 'events' to container
+  #
+  # @example Sample events
+  #   events:
+  #     'click': -> # this will raise on container click
+  #     'click .foo': -> # this will raise on .foo click
+  #     'click $foo': -> #this will search for selector of foo element
+  #
   __delegateEvents: ->
     module = this
     events = @__collectEvents()

data/app/assets/javascripts/joosy/core/modules/events.js.coffee

@@ -1,22 +1,50 @@
+#
+# Basic events implementation
+#
+# @module
+#
 Joosy.Modules.Events =
+
+  #
+  # Waits for the list of given events to happen at least once. Then runs callback.
+  #
+  # @param [String] events              List of events to wait for separated by space
+  # @param [Function] callback          Action to run when all events were triggered at least once
+  #
   wait: (events, callback) ->
-    events = events.split /\s+/
+    events = events.split /\s+/ if Object.isString events
 
     @__oneShotEvents ||= []
     @__oneShotEvents.push [events, callback]
 
+  #
+  # Binds action to run each time any of given even was triggered
+  #
+  # @param [String] events              List of events separated by space
+  # @param [Function] callback          Action to run on trigger
+  #
   bind: (events, callback) ->
     events = events.split /\s+/
 
     @__boundEvents ||= []
     @__boundEvents.push [events, callback]
 
+  #
+  # Unbinds action from runing on trigger
+  #
+  # @param [Function] target            Action to unbind
+  #
   unbind: (target) ->
     for [events, callback], index in @__boundEvents
       if callback == target
         @__boundEvents.splice index, 1
         return
 
+  #
+  # Triggers event for {bind} and {wait}
+  #
+  # @param [String]           Name of event to trigger
+  #
   trigger: (event) ->
     Joosy.Modules.Log.debugAs @, "Event #{event} triggered"
     if @__oneShotEvents
@@ -34,3 +62,62 @@ Joosy.Modules.Events =
       for [events, callback] in @__boundEvents
         if events.has event
           callback()
+  
+  #
+  # Runs set of callbacks finializing with result callback
+  #
+  # @example Basic usage
+  #   Joosy.Events.synchronize (context) ->
+  #     contet.do (done) -> done()
+  #     contet.do (done) -> done()
+  #     content.after ->
+  #       console.log 'Success!'
+  #
+  # @param [Function] block           Configuration block (see example)
+  #
+  synchronize: (block) ->
+    context = new Joosy.Modules.Events.SynchronizationContext(this)
+    block.call(this, context)
+    
+    @wait context.expectations, => context.after.call(this)
+
+    context.actions.each (data) =>
+      data[0].call this, =>
+        @trigger data[1]
+        
+#
+# Internal representation of {Joosy.Modules.Events#synchronize} context
+#
+# @see Joosy.Modules.Events#synchronize
+#
+class Joosy.Modules.Events.SynchronizationContext
+  @uid = 0
+
+  constructor: (@parent) ->
+    @expectations = []
+    @actions = []
+
+  #
+  # Internal simple counter to separate given synchronization actions
+  #
+  uid: ->
+    @constructor.uid += 1
+
+  #
+  # Registeres another async function that should be synchronized
+  #
+  # @param [Function] action        `(Function) -> null` to call.
+  #   Should call given function to mark itself complete.
+  #
+  do: (action) ->
+    event = "synchro-#{@uid()}"
+    @expectations.push event
+    @actions.push [action, event]
+
+  #
+  # Registers finalizer: the action that will be called when all do-functions 
+  #   marked themselves as complete.
+  #
+  # @param [Function] after       Function to call.
+  #
+  after: (@after) ->

data/app/assets/javascripts/joosy/core/modules/filters.js.coffee

@@ -1,4 +1,19 @@
+#
+# Filters registration routines
+#
+# @module
+#
 Joosy.Modules.Filters =
+
+  #
+  # Defines static registration routines
+  #
+  # @example Set of methods
+  #   class Test
+  #     @beforeLoad -> # supposed to run before load and control loading queue
+  #     @afterLoad -> # supposed to run after load to finalize loading
+  #     @afterUnload -> # supposed to run after unload to collect garbage
+  #
   included: ->
     @beforeLoad = (callback) ->
       unless @::hasOwnProperty '__beforeLoads'
@@ -15,6 +30,9 @@ Joosy.Modules.Filters =
         @::__afterUnloads = [].concat @.__super__.__afterUnloads || []
       @::__afterUnloads.push callback
 
+  #
+  # Runs filters registered as beforeLoad
+  #
   __runBeforeLoads: (opts...) ->
     unless @__beforeLoads?.length > 0
       return true
@@ -28,6 +46,9 @@ Joosy.Modules.Filters =
 
     return flag
 
+    #
+    # Runs filters registered as afterLoad
+    #
   __runAfterLoads: (opts...) ->
     if @__afterLoads?.length > 0
       for filter in @__afterLoads
@@ -35,6 +56,9 @@ Joosy.Modules.Filters =
           filter = @[filter]
         filter.apply @, opts
 
+  #
+  # Runs filters registered as afterUnload
+  #
   __runAfterUnloads: (opts...) ->
     if @__afterUnloads?.length > 0
       for filter in @__afterUnloads

data/app/assets/javascripts/joosy/core/modules/log.js.coffee

@@ -1,4 +1,13 @@
+#
+# Wrappers for console.log
+#
+# @module
+#
 Joosy.Modules.Log =
+  
+  #
+  # Checks if console is available and proxies given arguments directly to `console.log`
+  #
   log: (args...) ->
     return unless console?
 
@@ -8,10 +17,19 @@ Joosy.Modules.Log =
     else
       console.log args.first()
 
+  #
+  # Runs `log` if debug is active
+  #
   debug: (args...) ->
     return unless Joosy.debug
     @log args...
 
+  #
+  # Logs given message wrapping it with description of given object (class name)
+  #
+  # @param [Object] context           The class required to be described in log message
+  # @param [String] string            Message to log
+  #
   debugAs: (context, string, args...) ->
     return unless Joosy.debug
     context = Joosy.Module.__className(context) || 'unknown context'

data/app/assets/javascripts/joosy/core/modules/module.js.coffee

@@ -1,9 +1,30 @@
 moduleKeywords = ['included', 'extended']
 
+#
+# Base Joosy class extending Coffee class with module-like injections 
+#   and other tiny stuff.
+#
 class Joosy.Module
+  #
+  # Sets the default namespace for all Joosy descendants.
+  # This is used in {Joosy.namespace} magic.
+  #
   @__namespace__: []
 
-  @__className = (klass) ->
+  #
+  # Gets Object/Class class name.
+  #
+  # @note Never use this to make some magical auto-suggestions!!!
+  #   Remember: minifcation will rename your classes. Therefore it
+  #   is only intended for development debugging purposes.
+  #
+  # @note Go @jashkenas Go! Give us https://github.com/jashkenas/coffee-script/issues/2052.
+  #   Please go vote for this feature if you are reading this. It will
+  #   give us ability to eleminate a lot of boilerplate for you.
+  #
+  # @return [String]
+  #
+  @__className: (klass) ->
     unless Object.isFunction(klass)
       klass = klass.constructor
 
@@ -12,6 +33,14 @@ class Joosy.Module
     else
       klass.toString().replace /^function ([a-zA-Z]+)\([\s\S]+/, '$1'
 
+  #
+  # Determines if class A has class B in its ancestors.
+  #
+  # @param [Class] what       Class to check againt
+  # @param [Class] klass      Possible ancestor to search for
+  #
+  # @return [Boolean]
+  #
   @hasAncestor: (what, klass) ->
     unless what? && klass?
       return false
@@ -25,6 +54,19 @@ class Joosy.Module
 
     false
     
+  #
+  # Simple and fast shallow merge implementation.
+  #
+  # This is here due to: https://github.com/andrewplummer/Sugar/issues/100.
+  # This bug was closed and we got some performance but this implementation is
+  # still like 10x fater for basic tasks.
+  #
+  # @param [Object] destination       Object to extend
+  # @param [Object] source            Source of new properties
+  # @param [Boolean] unsafe           Determines if we should rewrite destination properties
+  #
+  # @return [Object]                  The new and mighty destination Object
+  #
   @merge: (destination, source, unsafe=true) ->
     for key, value of source
       if source.hasOwnProperty(key)
@@ -32,6 +74,11 @@ class Joosy.Module
           destination[key] = value
     destination
 
+  #
+  # Mixes given object as dynamic methods
+  #
+  # @param [Object] object          Module object
+  #
   @include: (object) ->
     unless object
       throw new Error 'include(object) requires obj'
@@ -43,6 +90,11 @@ class Joosy.Module
     object.included?.apply this
     null
 
+  #
+  # Mixes given object as static methods
+  #
+  # @param [Object] object          Module object
+  #
   @extend: (object) ->
     unless object
       throw new Error 'extend(object) requires object'

data/app/assets/javascripts/joosy/core/modules/renderer.js.coffee

@@ -1,13 +1,28 @@
 #= require_tree ../templaters
 #= require metamorph
 
+#
+# Core DOM rendering mechanics
+#
+# @module
+# @todo           Describe this scary thing o_O
+#
 Joosy.Modules.Renderer =
 
+  #
+  # Default behavior for non-set renderer (empty template?)
+  #
   __renderer: ->
     throw new Error "#{Joosy.Module.__className @constructor} does not have an attached template"
 
   __helpers: null
 
+  #
+  # Defines class-level helpers: @view and @helpers
+  #
+  # View (@view): Sets the curent template by specifying its name or lambda
+  # Helpers (@helpers): Lists set of helpers' namespaces to include
+  #
   included: ->
     @view = (template, options={}) ->
       if Object.isFunction template
@@ -77,6 +92,7 @@ Joosy.Modules.Renderer =
     stack = @__renderingStackChildFor parentStackPointer
     
     stack.template = template
+    stack.locals   = locals
     
     isResource   = Joosy.Module.hasAncestor locals.constructor, Joosy.Resource.Generic
     isCollection = Joosy.Module.hasAncestor locals.constructor, Joosy.Resource.Collection
@@ -91,11 +107,6 @@ Joosy.Modules.Renderer =
     
     if !Object.isObject(locals) && !isResource && !isCollection
       throw new Error "#{Joosy.Module.__className @}> locals (maybe @data?) not in: dumb hash, Resource, Collection"
-
-    if isResource
-      stack.locals = locals.e
-    else
-      stack.locals = locals
       
     renderers =
       render: (template, locals={}) =>
@@ -105,7 +116,12 @@ Joosy.Modules.Renderer =
         
     context = =>
       data = {}
-      Joosy.Module.merge data, stack.locals
+
+      if isResource
+        Joosy.Module.merge data, stack.locals.e
+      else
+        Joosy.Module.merge data, stack.locals
+
       Joosy.Module.merge data, @__instantiateHelpers(), false
       Joosy.Module.merge data, renderers
       data

data/app/assets/javascripts/joosy/core/modules/time_manager.js.coffee

@@ -1,4 +1,16 @@
+#
+# Comfortable and clever wrappers for timeouts management
+#
+# @module
+#
 Joosy.Modules.TimeManager =
+  
+  #
+  # Registeres timeout for current object
+  #
+  # @param [Integer] timeout          Miliseconds to wait
+  # @param [Function] action          Action to run on timeout
+  #
   setTimeout: (timeout, action) ->
     @__timeouts ||= []
 
@@ -7,6 +19,12 @@ Joosy.Modules.TimeManager =
 
     timer
 
+  #
+  # Registeres interval for current object
+  #
+  # @param [Integer] delay            Miliseconds between runs
+  # @param [Function] action          Action to run
+  #
   setInterval: (delay, action) ->
     @__intervals ||= []
 
@@ -15,6 +33,9 @@ Joosy.Modules.TimeManager =
 
     timer
 
+  #
+  # Drops all registered timeouts and intervals for this object
+  #
   __clearTime: ->
     if @__intervals
       for entry in @__intervals

data/app/assets/javascripts/joosy/core/modules/widgets_manager.js.coffee

@@ -1,4 +1,16 @@
+#
+# Widgets management routines
+#
+# @module
+#
 Joosy.Modules.WidgetsManager =
+
+  #
+  # Registeres and runs widget inside specified container
+  #
+  # @param [DOM] container              jQuery or direct dom node object
+  # @param [Joosy.Widget] widget        Class or object of Joosy.Widget to register
+  #
   registerWidget: (container, widget) ->
     if Joosy.Module.hasAncestor widget, Joosy.Widget
       widget = new widget()
@@ -8,11 +20,19 @@ Joosy.Modules.WidgetsManager =
 
     widget
 
+  #
+  # Unregisteres and destroys widget
+  #
+  # @param [Joosy.Widget] widget          Object of Joosy.Widget to unregister
+  #
   unregisterWidget: (widget) ->
     widget.__unload()
 
     @__activeWidgets.splice @__activeWidgets.indexOf(widget), 1
 
+  #
+  # Gathers widgets definitions from current and super classes
+  #
   __collectWidgets: ->
     widgets = Object.extended @widgets || {}
 
@@ -22,6 +42,9 @@ Joosy.Modules.WidgetsManager =
 
     widgets
 
+  #
+  # Intialize all widgets for current object
+  #
   __setupWidgets: ->
     widgets    = @__collectWidgets()
     registered = Object.extended()
@@ -52,6 +75,9 @@ Joosy.Modules.WidgetsManager =
       value.each (widget, count) =>
         Joosy.Modules.Log.debugAs @, "Widget #{widget} registered at '#{selector}'. Elements: #{count}"
 
+  #
+  # Unregister all widgets for current object
+  #
   __unloadWidgets: ->
     if @__activeWidgets
       for widget in @__activeWidgets