joosy 1.2.0.alpha.41 → 1.2.0.alpha.51

data/source/joosy/widget.coffee

@@ -0,0 +1,385 @@
+#= require joosy/joosy
+#= require joosy/modules/log
+#= require joosy/modules/events
+#= require joosy/modules/dom
+#= require joosy/modules/renderer
+#= require joosy/modules/time_manager
+#= require joosy/modules/filters
+
+#
+# Base class for all Joosy Widgets.
+#
+# Joosy expects you to perceive your actual application as a tree of widgets. Internally all high-level
+# containers like {Layout} and {Page} are inheriting from Widget. Widget contains logic for:
+#
+#   * Recursive nesting (widgets can contain widgets, etc.)
+#   * Loading and Unloading flows (proper initializations, destructions and replacements)
+#   * Filtering (afterLoad, beforeLoad and the family of paint filters)
+#
+# During the bootstrap, widgets can take either dependent or independent strategy. Dependent widgets form
+# "dependent chains" that will be rendered together (HTML will be injected into DOM atomically). Such chains
+# use paint filters of the top elements. Independent widgets on the other hand load on their own behalf and
+# use their own paint filters. To understand this better, here is the sample:
+# 
+# Let's say we have 4 widgets A, B, C and D nested into each other:
+#
+# A is the root widget
+# B is nested into A. It does not define itself as an independent and therefore defaults to dependent rendering
+# C is nested into B. It defines itself as an independent children
+# D is nested into C. It does not define itself as an independent and therefore defaults to dependent rendering
+#
+# Then total chain of asynchronous callbacks goes with the following scenario.
+# 
+# 1. A collects all the fetches from the whole tree recursively and starts them in parallel.
+# 2. A runs erase on the previous same-level widget (attribute `@previos`) if one is given.
+# 3. A runs beforePaint on itself when 2 is done.
+# 4. A waits for step 3 and all fetches of containers in recursive dependency chain (equal to B) to complete.
+# 5. A builds resulting HTML using:
+#   * HTML of dependency chain (B)
+#   * HTML of independent containers that are ready to be rendered (their own recursive dependency chain is fetched completely).
+# 5. A forks every independent container that was not rendered (C).
+# 6. A starts paint on itself and injects HTML into DOM.
+# 7. C repeats steps 2-7 using itself as a base and D as its own recursive dependency chain
+#
+# @include Joosy.Modules.Log
+# @include Joosy.Modules.Events
+# @include Joosy.Modules.DOM
+# @include Joosy.Modules.Renderer
+# @include Joosy.Modules.TimeManager
+# @include Joosy.Modules.Filters
+#
+class Joosy.Widget extends Joosy.Module
+  @include Joosy.Modules.Log
+  @include Joosy.Modules.Events
+  @include Joosy.Modules.DOM
+  @include Joosy.Modules.Renderer
+  @include Joosy.Modules.TimeManager
+  @include Joosy.Modules.Filters
+
+  #
+  # Extends widgets mapping
+  #
+  # Pass either widget class or instance as a value. Given lambdas are evaluated.
+  #
+  # @example
+  #   @mapWidgets
+  #     '.selector1': Widget1
+  #     '.selector2': -> @widget = new Widget2
+  #
+  @mapWidgets: (map) ->
+    unless @::hasOwnProperty "__widgets"
+      @::__widgets = Object.clone(@.__super__.__widgets) || {}
+    Object.merge @::__widgets, map
+
+  #
+  # Declares widget as indepent changing the way it behaves during the bootstrap
+  #
+  @independent: ->
+    @::__independent = true
+
+  @registerPlainFilters \
+    #
+    # @method .beforeLoad(callback)
+    #
+    # Initialization hook that runs in the very begining of bootstrap process.
+    # Call it multiple times to attach several hooks.
+    #
+    'beforeLoad',
+
+    #
+    # @method .afterLoad(callback)
+    #
+    # Hook that runs after the section was properly loaded and injected into DOM.
+    # Call it multiple times to attach several hooks.
+    #
+    'afterLoad',
+
+    #
+    # @method .beforeUnload(callback)
+    #
+    # Hook that finalizes section desctruction.
+    # Call it multiple times to attach several hooks.
+    #
+    'afterUnload'
+
+  @registerSequencedFilters \
+
+    #
+    # @method .beforePaint(callback)
+    #
+    # Sets the method which will controll the painting preparation proccess.
+    #
+    # This method will be called right ater previous section erase and in parallel with
+    #   new 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) ->
+    #     @$preloader.slideDown -> complete()
+    #
+    #
+    'beforePaint',
+
+    #
+    # @method .paint(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',
+
+    #
+    # @method .erase(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',
+
+    #
+    # @method .fetch(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'
+
+  #
+  # @param [Hash] params              Arbitrary parameters
+  # @param [Joosy.Layout] previous    Same-level widget to replace
+  #
+  constructor: (@params, @previous) ->
+
+  #
+  # 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 Object.isString $container
+      $container = @__normalizeSelector($container)
+
+    widget = @__normalizeWidget(widget)
+    widget.__bootstrapDefault $container
+
+    @__nestedSections ||= []
+    @__nestedSections.push widget
+
+    widget
+
+  #
+  # Unregisteres and destroys widget
+  #
+  # @param [Joosy.Widget] widget          Object of Joosy.Widget to unregister
+  #
+  unregisterWidget: (widget) ->
+    widget.__unload()
+
+    @__nestedSections.splice @__nestedSections.indexOf(widget), 1
+
+  replaceWidget: (widget, replacement) ->
+    replacement = @__normalizeWidget(replacement)
+    replacement.previous = widget
+
+    replacement.__bootstrapDefault widget.$container
+
+  #
+  # @see Joosy.Router.navigate
+  #
+  navigate: ->
+    Joosy.Router?.navigate arguments...
+
+  #
+  # This is required by {Joosy.Modules.Renderer}
+  # Sets the base template dir to app_name/templates/widgets
+  #
+  __renderSection: ->
+    'widgets'
+
+  #
+  # Collects statically registered widgets to form default nesting map
+  #
+  __nestingMap: ->
+    map = {}
+
+    for selector, widget of @__widgets
+      widget = @__normalizeWidget(widget)
+
+      map[selector] =
+        instance: widget
+        nested: widget.__nestingMap()
+
+    map
+
+  #
+  # Shortcut for default bootstrap using statically registered widgets
+  #
+  # @param [jQuery] $container                 DOM container to inject to
+  #
+  __bootstrapDefault: ($container) ->
+    @__bootstrap @__nestingMap(), $container
+
+  #
+  # Bootstraps the section with given nestings at given container
+  #
+  # @example
+  #   nestingMap =
+  #     '#page':
+  #       instance: page
+  #       nested:
+  #         '#widget1': {instance: widget1}
+  #
+  #   layout.__bootstrap nestingMap, Joosy.Application.content()
+  #
+  # @param [Object] nestingMap              Map of nested sections to bootstrap
+  # @param [jQuery] $container              DOM container to inject into
+  # @param [boolean] fetch                  Boolean flag used to avoid double fetch during recursion
+  #
+  __bootstrap: (nestingMap, @$container, fetch=true) ->
+    @wait 'section:fetched section:erased', =>
+      @__runPaints [], =>
+        @__paint nestingMap, @$container
+
+    @__erase()
+    @__fetch(nestingMap) if fetch
+
+  #
+  # Recursively starts fetching for the whole nested tree. As soon as fetching is done, section
+  # triggers rememberable event 'section:fetched'
+  #
+  # Section can be considered fetched if (and triggers event when):
+  #   * Its fetchers are complete
+  #   * All the fetchers of all dependent nestings are complete
+  #
+  __fetch: (nestingMap) ->
+    @data = {}
+
+    @synchronize (context) =>
+      Object.each nestingMap, (selector, section) ->
+        section.instance.__fetch(section.nested)
+
+        if !section.instance.__independent
+          context.do (done) ->
+            section.instance.wait 'section:fetched', done
+
+      context.do (done) =>
+        @__runFetchs [], done
+
+      context.after =>
+        @trigger name: 'section:fetched', remember: true
+
+  #
+  # Runs erasing chain for the previous section and beforePaints for current
+  #
+  __erase: ->
+    if @previous?
+      @previous.__runErases [], =>
+        @previous.__unload()
+
+        @__runBeforePaints [], =>
+          @trigger name: 'section:erased', remember: true
+    else
+      @__runBeforePaints [], =>
+        @trigger name: 'section:erased', remember: true
+
+  #
+  # Builds HTML of section and its dependent nestings and injects it into DOM
+  #
+  __paint: (nestingMap, @$container) ->
+    @__nestedSections = []
+    @$container.html @__renderDefault?(@data || {})
+
+    @__load()
+
+    Object.each nestingMap, (selector, section) =>
+      @__nestedSections.push section.instance
+
+      $container = @__normalizeSelector(selector)
+
+      if !section.instance.__independent || section.instance.__triggeredEvents?['section:fetched']
+        section.instance.__paint section.nested, $container
+      else
+        section.instance.__bootstrap section.nested, $container, false
+
+  #
+  # Initializes section that was injected into DOM
+  #
+  __load: ->
+    @__assignElements()
+    @__delegateEvents()
+    @__runAfterLoads()
+
+  #
+  # Deinitializes section that is preparing to be removed from DOM
+  #
+  __unload: ->
+    section.__unload() for section in @__nestedSections
+    delete @__nestedSections
+
+    @__clearContainer()
+    @__clearTime()
+    @__removeMetamorphs()
+    @__runAfterUnloads()
+    delete @previous
+
+  #
+  # Normalizes selector and returns jQuery wrap
+  #
+  # Selector can be one of:
+  #
+  #   * $container - gets raw main container
+  #   * $elem      - attempts to get values from {Joosy.Modules.DOM} mappings
+  #   * .selector  - raw CSS selectors pass as-is
+  #
+  __normalizeSelector: (selector) ->
+    if selector == '$container'
+      @$container
+    else
+      $(@__extractSelector(selector), @$container)
+
+  #
+  # Normalizes widget descrpition to its instance
+  #
+  # Besides already being instance it cann be either class or lambda
+  #
+  __normalizeWidget: (widget) ->
+    if Object.isFunction(widget) && !Joosy.Module.hasAncestor(widget, Joosy.Widget)
+      widget = widget.call(@)
+
+    if Joosy.Module.hasAncestor widget, Joosy.Widget
+      widget = new widget
+
+    widget
+
+# AMD wrapper
+if define?.amd?
+  define 'joosy/widget', -> Joosy.Widget

data/source/joosy.coffee

@@ -0,0 +1 @@
+#= require joosy/application

data/spec/helpers/matchers.coffee

@@ -29,6 +29,12 @@ beforeEach ->
 
       return true
 
+    toEqualHTML: (string) ->
+      html     = @actual.replace(/>\s+</g, '><')
+      @message = -> "Expected '#{html}' to equal '#{string}'"
+
+      html == string
+
     #
     # Checks the exact equality of tag including attributes and content
     # with the posibility to check attributes values by regexp
@@ -39,7 +45,8 @@ beforeEach ->
     #
     toBeTag: (tagName, content, attrs) ->
       @message = =>
-        "Expected #{@actual} to be a tag #{tagName} with attributes #{JSON.stringify attrs} and content '#{content}'"
+        actual = $('<div>').append(@actual).html()
+        "Expected '#{actual}' to be a tag #{tagName} with attributes #{JSON.stringify attrs} and content '#{content}'"
 
       tag = $ @actual
 

data/spec/joosy/core/application_spec.coffee

@@ -1,39 +1,140 @@
 describe "Joosy.Application", ->
 
   beforeEach ->
-    sinon.stub Joosy.Router, "__setupRoutes"
+    sinon.stub Joosy.Router, "setup"
     @$ground.seed()
 
   afterEach ->
-    Joosy.Router.__setupRoutes.restore()
+    Joosy.Router.setup.restore()
+    Joosy.Application.reset()
 
   it "initializes", ->
-    Joosy.Application.initialize 'app', '#application', foo: {bar: 'baz'}
+    Joosy.Application.initialize '#application', foo: {bar: 'baz'}
     expect(Joosy.Application.page).toBeUndefined()
     expect(Joosy.Application.selector).toEqual '#application'
-    expect(Joosy.Router.__setupRoutes.callCount).toEqual 1
-    expect(Joosy.Application.name).toEqual 'app'
+    expect(Joosy.Router.setup.callCount).toEqual 1
     expect(Joosy.Application.config.foo.bar).toEqual 'baz'
     expect(Joosy.Application.content()).toEqual $('#application')
 
-  it "manages pages", ->
-    spy = sinon.spy()
+  it "merges config", ->
+    Joosy.Application.initialize '#application', router: {html5: true}
+    expect(Joosy.Application.config.router.html5).toEqual true
+    expect(Joosy.Application.config.router.base).toEqual ''
 
-    class Page1
-      constructor: spy
+  describe "page changer", ->
+    beforeEach ->
+      Joosy.Application.initialize @$ground
 
-    class Page2
-      constructor: spy
+      class @Layout extends Joosy.Layout
+        @view (locals) -> locals.page 'div'
 
-    Joosy.Application.setCurrentPage(Page1, {foo: 'bar'})
+      class @Page extends Joosy.Page
+        @view -> "page"
 
-    expect(Joosy.Application.page instanceof Page1).toBeTruthy()
-    expect(spy.callCount).toEqual 1
-    expect(spy.args[0]).toEqual [{foo: 'bar'}, undefined]
+    it "sets page to clean ground", ->
+      Joosy.Application.changePage(@Page, {foo: 'bar'})
+      expect(Joosy.Application.page instanceof @Page).toBeTruthy()
+      expect(Joosy.Application.page.params).toEqual foo: 'bar'
+      expect(@$ground.html()).toEqual 'page'
 
-    Joosy.Application.setCurrentPage(Page2, {bar: 'baz'})
+    it "changes from page to page", ->
+      Joosy.Application.changePage(@Page, {foo: 'bar'})
+      expect(@$ground.html()).toEqual 'page'
+      page = Joosy.Application.page
 
-    expect(Joosy.Application.page instanceof Page2).toBeTruthy()
-    expect(spy.callCount).toEqual 2
-    expect(spy.args[1][0]).toEqual {bar: 'baz'}
-    expect(spy.args[1][1] instanceof Page1).toBeTruthy()
+      Joosy.Application.changePage(@Page, {foo: 'bar'})
+      expect(@$ground.html()).toEqual 'page'
+      expect(Joosy.Application.page.previous).toEqual page
+
+    it "sets layouted page to clean ground", ->
+      @Page.layout @Layout
+
+      Joosy.Application.changePage(@Page, {foo: 'bar'})
+      expect(Joosy.Application.page instanceof @Page).toBeTruthy()
+      expect(Joosy.Application.page.params).toEqual foo: 'bar'
+      expect(Joosy.Application.page.layout.params).toEqual foo: 'bar'
+      expect(@$ground.html()).toBeTag 'div', 'page', id: /__joosy\d+/
+
+    it "changes from layouted page to layouted page", ->
+      @Page.layout @Layout
+
+      Joosy.Application.changePage(@Page, {foo: 'bar'})
+      expect(@$ground.html()).toBeTag 'div', 'page', id: /__joosy\d+/
+      page   = Joosy.Application.page
+      layout = page.layout
+
+      Joosy.Application.changePage(@Page, {foo: 'bar'})
+      expect(@$ground.html()).toBeTag 'div', 'page', id: /__joosy\d+/
+      expect(Joosy.Application.page.previous).toEqual page
+      expect(Joosy.Application.page.layout).toEqual layout
+
+    it "changes from layouted page to page", ->
+      @Page.layout @Layout
+
+      Joosy.Application.changePage(@Page, {foo: 'bar'})
+      expect(@$ground.html()).toBeTag 'div', 'page', id: /__joosy\d+/
+      page   = Joosy.Application.page
+      layout = page.layout
+
+      class Page extends Joosy.Page
+        @view -> "page"
+
+      Joosy.Application.changePage(Page, {foo: 'bar'})
+      expect(@$ground.html()).toEqual 'page'
+      expect(Joosy.Application.page.previous).toEqual layout
+      expect(Joosy.Application.page.layout).toBeUndefined()
+
+    it "passes @data to @view", ->
+      class Layout extends Joosy.Layout
+        @fetch (complete) ->
+          expect(@data).toEqual {}
+          @data.foo = 'bar'
+          complete()
+
+        @view (locals) ->
+          expect(locals.foo).toEqual 'bar'
+
+      class Page extends Joosy.Page
+        @layout Layout
+
+        @fetch (complete) ->
+          expect(@data).toEqual {}
+          @data.foo = 'bar'
+          complete()
+
+        @view (locals) ->
+          expect(locals.foo).toEqual 'bar'
+
+      Joosy.Application.changePage Page
+
+    it "sequences paint hooks", ->
+      spies = []
+      11.times -> spies.push sinon.spy()
+
+      class Layout extends Joosy.Layout
+        @beforePaint (complete) -> spies[0](); complete()
+        @fetch       (complete) -> spies[2](); complete()
+        @paint       (complete) -> spies[3](); complete()
+
+        @view spies[4]
+
+      class PageA extends Joosy.Page
+        @layout Layout
+
+        @fetch       (complete) -> spies[1](); complete()
+        @erase       (complete) -> spies[6](); complete()
+        @view spies[5]
+
+      class PageB extends Joosy.Page
+        @layout Layout
+
+        @beforePaint (complete) -> spies[7](); complete()
+        @fetch       (complete) -> spies[8](); complete()
+        @paint       (complete) -> spies[9](); complete()
+
+        @view spies[10]
+
+      Joosy.Application.changePage PageA
+      Joosy.Application.changePage PageB
+
+      expect(spies).toBeSequenced()

data/spec/joosy/core/helpers/view_spec.coffee

@@ -4,11 +4,11 @@ describe "Joosy.Helpers.View", ->
   h = Joosy.Helpers.Application
 
   it "renders tag with string content", ->
-    tag = h.tag 'div', {id: 'id'}, 'content'
+    tag = h.contentTag 'div', 'content', {id: 'id'}
     expect(tag).toEqual '<div id="id">content</div>'
 
   it "renders tag with lambda content", ->
-    tag = h.tag 'div', {id: 'id'}, -> 
-      h.tag 'div', {id: 'id2'}, 'content'
+    tag = h.contentTag 'div', {id: 'id'}, -> 
+      h.contentTag 'div', 'content', {id: 'id2'}
 
     expect(tag).toEqual '<div id="id"><div id="id2">content</div></div>'

data/spec/joosy/core/helpers/widgets_spec.coffee

@@ -7,15 +7,12 @@ describe "Joosy.Helpers.Widgets", ->
     class @Widget extends Joosy.Widget
       @view -> "test"
 
-    # Least possible configuration capable of using helper
-    class @Renderer extends Joosy.Module
-      @include Joosy.Modules.Renderer
-      @include Joosy.Modules.TimeManager
-      @include Joosy.Modules.WidgetsManager
+    class @Renderer extends Joosy.Page
 
     @renderer = new @Renderer
     @widget   = new @Widget
-    @template = (context) => context.widget 'div', @widget
+    @template = (context) =>
+      context.widget 'div', @widget
 
   it "renders widget tag", ->
     runs ->

data/spec/joosy/core/joosy_spec.coffee

@@ -1,10 +1,5 @@
 describe "Joosy", ->
 
-  it "initializes", ->
-    expect(Joosy.Application.config.debug).toBeFalsy()
-    expect(Joosy.Modules).toBeDefined()
-    expect(Joosy.Resources).toBeDefined()
-
   it "generates proper UUIDs", ->
     uuids = []
     2.times -> uuids.push Joosy.uuid()

data/spec/joosy/core/layout_spec.coffee

@@ -2,13 +2,7 @@ describe "Joosy.Layout", ->
 
   beforeEach ->
     class @Layout extends Joosy.Layout
-    @layout = new @Layout
-
-  it "has appropriate accessors", ->
-    callbackNames = ['beforePaint', 'paint', 'erase']
-    callbackNames.each (callbackName) =>
-      @Layout[callbackName] 'callback'
-      expect(@Layout::['__' + callbackName]).toEqual 'callback'
+    @layout = new @Layout $('#application')
 
   it "generates uid", ->
     @layout.page()
@@ -18,29 +12,9 @@ describe "Joosy.Layout", ->
     @layout.page()
     expect(@layout.content().selector).toEqual '#' + @layout.uid
 
-  it "has default view", ->
-    expect(@layout.__renderDefault instanceof Function).toBeTruthy()
-
   it "integrates with Router", ->
     target = sinon.stub Joosy.Router, 'navigate'
     @layout.navigate 'there'
     expect(target.callCount).toEqual 1
     expect(target.alwaysCalledWithExactly 'there').toBeTruthy()
-    Joosy.Router.navigate.restore()
-
-  it "loads", ->
-    spies = []
-    spies.push sinon.spy(@layout, '__assignElements')
-    spies.push sinon.spy(@layout, '__delegateEvents')
-    spies.push sinon.spy(@layout, '__setupWidgets')
-    spies.push sinon.spy(@layout, '__runAfterLoads')
-    @layout.__load(@$ground)
-    expect(spies).toBeSequenced()
-
-  it "unloads", ->
-    spies = []
-    spies.push sinon.spy(@layout, '__clearTime')
-    spies.push sinon.spy(@layout, '__unloadWidgets')
-    spies.push sinon.spy(@layout, '__runAfterUnloads')
-    @layout.__unload()
-    expect(spies).toBeSequenced()
+    Joosy.Router.navigate.restore()