joosy 0.1.0.RC2 → 0.1.0.RC3

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

@@ -8,6 +8,14 @@
 #= require joosy/core/modules/widgets_manager
 #= require joosy/core/modules/filters
 
+#
+# Base class for all of your Joosy Pages.
+# @see http://guides.joosy.ws/guides/layouts-pages-and-routing.html
+#
+# @example Sample application page
+#   class @RumbaPage extends Joosy.Layout
+#     @view 'rumba'
+#
 class Joosy.Page extends Joosy.Module
   @include Joosy.Modules.Log
   @include Joosy.Modules.Events
@@ -17,32 +25,173 @@ class Joosy.Page extends Joosy.Module
   @include Joosy.Modules.WidgetsManager
   @include Joosy.Modules.Filters
 
+  #
+  # Default layout is no layout.
+  #
   layout: false
+  
+  #
+  # Previous page.
+  #
   previous: false
+  
+  #
+  # Route params.
+  #
   params: false
+  
+  #
+  # Prefetched page data.
+  #
   data: false
 
-  @fetch: (callback) ->
-    @::__fetch = callback
-
-  @scroll: (element, options={}) ->
-    @::__scrollElement = element
-    @::__scrollSpeed = options.speed || 500
-    @::__scrollMargin = options.margin || 0
-
+  #
+  # Sets layout for current page
+  #
+  # @param [Class] layoutClass      Layout to use
+  #
   @layout: (layoutClass) ->
     @::__layoutClass = layoutClass
 
+  #
+  # Sets the method which will controll the painting preparation proccess.
+  #
+  # This method will be called right ater previous page {Joosy.Page.erase} and in parallel with
+  #   page 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 page.
+  #
+  # @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
+
+  #
+  # @todo Does anybody have idea why we could need this method?
+  #   Looks like something should be removed from here and bootstrap proccess.
+  #
   @afterPaint: (callback) ->
     @::__afterPaint = 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 page 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.
+  #
+  # @example Basic usage
+  #   @fetch (complete) ->
+  #     $.get '/rumbas', (@data) => complete()
+  #
+  @fetch: (callback) ->
+    @::__fetch = callback
+    
+  #
+  # Sets the several separate methods that will fetch data in parallel.
+  #
+  # @note This will work through {Joosy.Modules.Events#synchronize}
+  #
+  # @example Basic usage
+  #   @fetchSynchronized (context) ->
+  #     context.do (done) ->
+  #       $.get '/rumbas', (data) =>
+  #         @data.rumbas = data
+  #         done()
+  #     
+  #     context.do (done) ->
+  #       $.get '/kutuzkas', (data) =>
+  #         @data.kutuzkas = data
+  #         done()
+  #
+  @fetchSynchronized: (callback) ->
+    @::__fetch = (complete) ->
+      @synchronize (context) ->
+        context.after -> complete()
+        callback.call(this, context)
+
+  #
+  # Sets the position where page will be scrolled to after load.
+  #
+  # @note If you use animated scroll joosy will atempt to temporarily fix the 
+  #   height of your document while scrolling to prevent jump effect.
+  #
+  # @param [jQuery] element         Element to scroll to
+  # @param [Hash] options
+  #
+  # @option options [Integer] speed       Sets the animation duration (500 is default)
+  # @option options [Integer] margin      Defines the margin from element position.
+  #   Can be negative.
+  #
+  @scroll: (element, options={}) ->
+    @::__scrollElement = element
+    @::__scrollSpeed = options.speed || 500
+    @::__scrollMargin = options.margin || 0
+  
+  #
+  # Sets the page HTML title.
+  #
+  # @note Title will be reverted on unload.
+  #
+  # @param [String] title       Title to set.
+  #
+  @title: (title, separator=' / ') ->
+    @afterLoad ->
+      titleStr = if Object.isFunction(title) then title.apply(this) else title
+      titleStr = titleStr.join(separator) if Object.isArray(titleStr)
+      @__previousTitle = document.title
+      document.title = titleStr
+    
+    @afterUnload ->
+      document.title = @__previousTitle
+
+  #
+  # Constructor is very destructive (c), it calls bootstrap directly so use with caution.
+  #
+  # @params [Hash] params             Route params
+  # @params [Joosy.Page] previous     Previous page to unload
+  #
   constructor: (@params, @previous) ->
+    Joosy.Application.loading = true
+    
     @__layoutClass ||= ApplicationLayout
 
     if @__runBeforeLoads @params, @previous
@@ -51,18 +200,42 @@ class Joosy.Page extends Joosy.Module
       else
         @__bootstrap()
 
+  #
+  # @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/pages
+  #
   __renderSection: ->
     'pages'
 
+  #
+  # Freezes the page height through $(html).
+  #
+  # Required to implement better {Joosy.Page.scroll} behavior.
+  #
   __fixHeight: ->
     $('html').css 'min-height', $(document).height()
-    
+  
+  #
+  # Undo {#__fixHeight}
+  #
   __releaseHeight: ->
     $('html').css 'min-height', ''
 
+  #
+  # Page bootstrap proccess
+  #
+  #   * {Joosy.Modules.Container#refreshElements}
+  #   * {Joosy.Modules.Container#__delegateEvents}
+  #   * {Joosy.Modules.WidgetsManager#__setupWidgets}
+  #   * {Joosy.Modules.Filters#__runAfterLoads}
+  #   * Scrolling
+  #
   __load: ->
     @refreshElements()
     @__delegateEvents()
@@ -74,9 +247,19 @@ class Joosy.Page extends Joosy.Module
       $('html, body').animate {scrollTop: scroll}, @__scrollSpeed, =>
         if @__scrollSpeed != 0
           @__releaseHeight()
+    Joosy.Application.loading = false
+    @trigger 'loaded'
 
     Joosy.Modules.Log.debugAs @, "Page loaded"
 
+  #
+  # Page destruction proccess.
+  #
+  #   * {Joosy.Modules.TimeManager#__clearTime}
+  #   * {Joosy.Modules.WidgetsManager#__unloadWidgets}
+  #   * {Joosy.Modules.Renderer#__removeMetamorphs}
+  #   * {Joosy.Modules.Filters#__runAfterUnloads}
+  #
   __unload: ->
     @__clearTime()
     @__unloadWidgets()
@@ -84,19 +267,35 @@ class Joosy.Page extends Joosy.Module
     @__runAfterUnloads @params, @previous
     delete @previous
 
+  #
+  # Proxies callback through possible async wrapper.
+  #
+  # If wrapper is defined, it will be called with given callback as one of parameters.
+  # If wrapper is not defined callback will be called directly.
+  #
+  # @note Magic People Voodoo People
+  #
+  # @param [Object] entity        Object possibly containing wrapper method
+  # @param [String] receiver      String name of wrapper method inside entity
+  # @param [Hash] params          Params to send to wrapper, callback will be 
+  #   attached as the last of them.
+  # @param [Function] callback    Callback to run
+  #
   __callSyncedThrough: (entity, receiver, params, callback) ->
     if entity?[receiver]?
       entity[receiver].apply entity, params.clone().add(callback)
     else
       callback()
-
-  # Boot Sequence:
+  
+  #
+  # The single page (without layout reloading) bootstrap logic
   #
-  # previous::erase  \
-  # previous::unload  \
-  # beforePaint        \
-  #                     > paint
-  # fetch             /
+  # @example Hacky boot sequence description
+  #   previous::erase  \
+  #   previous::unload  \
+  #   beforePaint        \
+  #                       > paint
+  #   fetch             /
   #
   __bootstrap: ->
     Joosy.Modules.Log.debugAs @, "Boostraping page"
@@ -127,6 +326,16 @@ class Joosy.Page extends Joosy.Module
       Joosy.Modules.Log.debugAs @, "Fetch complete"
       @trigger 'dataReceived'
 
+  #
+  # The page+layout bootstrap logic
+  #
+  # @example Hacky boot sequence description
+  #   previous::erase  \
+  #   previous::unload  \
+  #   beforePaint        \
+  #                       > paint
+  #   fetch             /
+  #
   __bootstrapLayout: ->
     Joosy.Modules.Log.debugAs @, "Boostraping page with layout"
     @layout = new @__layoutClass(@params)

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

@@ -1,5 +1,13 @@
+#
 # Preloader stub
+#
+# @module
+#
 @Preloader =
+
+  #
+  # Mocks loader to do nothing if Joosy is already here
+  #
   load: (libraries, options) ->
     @[key] = val for key, val of options
     @complete?.call window

data/app/assets/javascripts/joosy/core/resource/collection.js.coffee

@@ -1,17 +1,17 @@
 #
-# Basic collection of Resources
-# Turns JSON array into array of Resources and manages them
+# Basic collection of Resources.
+# Turns JSON array into array of Resources and manages them.
 #
-# Generally you should not use Collection directly. It will be
-# automatically created by things like Joosy.Resource.Generic#map 
-# or Joosy.Resource.REST#find.
+# @note You should not use Collection directly. It will be
+#   automatically created by things like {Joosy.Resource.Generic.map} 
+#   or {Joosy.Resource.REST.find}.
 #
-# Example:
+# @example Basic sample
 #   class R extends Joosy.Resource.Generic
 #     @entity 'r'
-#
+#     
 #   collection = new Joosy.Resource.Collection(R)
-#
+#     
 #   collection.reset [{foo: 'bar'}, {foo: 'baz'}]
 #   collection.each (resource) ->
 #     resource('foo')
@@ -22,25 +22,46 @@ class Joosy.Resource.Collection extends Joosy.Module
   #
   # Allows to modify data before it gets stored
   #
+  # @note Supposed to be used in descendants
+  #
   # @param [Function] action    `(Object) -> Object` to call
   #
   @beforeLoad: (action) -> @::__beforeLoad = action
   
+  #
+  # Sets the default model for collection
+  #
+  # @note Supposed to be used in descendants
+  #
+  # @param [Class] model     Model class
+  #
+  @model: (model) -> @::model = model
+  
   #
   # Modelized data storage
   #
   data: []
   
   #
-  # @param [Class] model    Resource class this collection will handle
+  # If model param was empty it will fallback to `@model`
+  # If both param and `@model` were empty it will throw an exception.
+  #
+  # @param [Class] model    Resource class which this collection will handle
   #
-  constructor: (@model) ->
+  constructor: (model=false) ->
+    @model = model if model
+    
+    if !@model
+      throw new Error "#{Joosy.Module.__className @}> model can't be empty"
   
   #
-  # Clears the storage and attempts to import given JSON
+  # Clears the storage and attempts to import given array
   #
-  # @param [Object] entities    Entities to import
-  # @param [Boolean] notify     Indicates whether to trigger 'changed' event
+  # @param [Array, Hash] entities     Array of entities to import.
+  #   If hash was given will seek for moodel name camelized and pluralized.
+  # @param [Boolean] notify           Indicates whether to trigger 'changed' event
+  #
+  # @return [Joosy.Resource.Collection]   Returns self.
   #
   reset: (entities, notify=true) ->
     if @__beforeLoad?
@@ -72,16 +93,24 @@ class Joosy.Resource.Collection extends Joosy.Module
   #
   # Calls callback for each Resource inside Collection
   #
-  # @param [Function] callback
+  # @param [Function] callback        `(mixed) -> mixed` to call for each Resource in collection
   #
   each: (callback) ->
     @data.each callback
-    
+
+  #
+  # Returns number of Resources inside Collection
+  #
+  size: ->
+    @data.length
+
   #
   # Gets first resource matching description (see Sugar.js Array#find)
   #
   # @param [Function] description       Callback matcher
   #
+  # @return [Joosy.Resource.Generic]
+  #
   find: (description) ->
     @data.find description
   
@@ -90,6 +119,8 @@ class Joosy.Resource.Collection extends Joosy.Module
   #
   # @param [Integer] id       Id to find
   #
+  # @return [Joosy.Resource.Generic]
+  #
   findById: (id) ->
     @data.find (x) -> x('id').toString() == id.toString()
   
@@ -98,6 +129,8 @@ class Joosy.Resource.Collection extends Joosy.Module
   #
   # @param [Integer] i    Index
   #
+  # @return [Joosy.Resource.Generic]
+  #
   at: (i) ->
     @data[i]
 
@@ -108,6 +141,8 @@ class Joosy.Resource.Collection extends Joosy.Module
   # @param [Resource] target    Resource by itself
   # @param [Boolean] notify     Indicates whether to trigger 'changed' event
   #
+  # @return [Joosy.Resource.Generic]        Removed element
+  #
   remove: (target, notify=true) ->
     if Object.isNumber target
       index = target
@@ -126,6 +161,8 @@ class Joosy.Resource.Collection extends Joosy.Module
   # @param [Integer] index          Index to add to. If omited will be pushed to the end
   # @param [Boolean] notify         Indicates whether to trigger 'changed' event
   #
+  # @return [Joosy.Resource.Generic]    Added element
+  #
   add: (element, index=false, notify=true) ->
     if index
       @data.splice index, 0, element