joosy 0.1.0.alpha → 1.0.0.RC1

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

@@ -0,0 +1,200 @@
+#= require_tree ../templaters
+#= require metamorph
+
+#
+# Core DOM rendering mechanics
+#
+# @mixin
+# @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
+        @::__renderer = template
+      else
+        @::__renderer = (locals={}) ->
+          if options.dynamic
+            @renderDynamic template, locals
+          else
+            @render template, locals
+
+    @helpers = (helpers...) ->
+      @::__helpers ||= []
+      helpers.map (helper) =>
+        module = Joosy.Helpers[helper]
+        unless module
+          throw new Error "Cannot find helper module #{helper}"
+
+        @::__helpers.push module
+
+      @::__helpers = @::__helpers.unique()
+
+  __instantiateHelpers: ->
+    unless @__helpersInstance
+      @__helpersInstance = Object.extended Joosy.Helpers.Application
+
+      if @onRefresh
+        @__helpersInstance.onRefresh = (callback) =>
+          @onRefresh callback
+
+      if @__helpers
+        for helper in @__helpers
+          Joosy.Module.merge @__helpersInstance, helper
+
+    @__helpersInstance
+
+  # If we do not have __proto__ available...
+  __proxifyHelpers: (locals) ->
+    if locals.hasOwnProperty '__proto__'
+      locals.__proto__ = @__instantiateHelpers()
+      locals
+    else
+      unless @__helpersProxyInstance
+        @__helpersProxyInstance = (locals) ->
+          Joosy.Module.merge this, locals
+
+        @__helpersProxyInstance.prototype = @__instantiateHelpers()
+
+      new @__helpersProxyInstance locals
+
+  render: (template, locals={}, parentStackPointer=false) ->
+    @__render false, template, locals, parentStackPointer
+
+  renderDynamic: (template, locals={}, parentStackPointer=false) ->
+    @__render true, template, locals, parentStackPointer
+
+  __render: (dynamic, template, locals={}, parentStackPointer=false) ->
+    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
+
+    if Object.isString template
+      if @__renderSection?
+        template = Joosy.Application.templater.resolveTemplate @__renderSection(), template, this
+
+      template = Joosy.Application.templater.buildView template
+    else if !Object.isFunction template
+      throw new Error "#{Joosy.Module.__className @}> template (maybe @view) does not look like a string or lambda"
+
+    if !Object.isObject(locals) && Object.extended().constructor != locals.constructor && !isResource && !isCollection
+      throw new Error "#{Joosy.Module.__className @}> locals (maybe @data?) not in: dumb hash, Resource, Collection"
+
+    renderers =
+      render: (template, locals={}) =>
+        @render template, locals, stack
+      renderDynamic: (template, locals={}) =>
+        @renderDynamic template, locals, stack
+
+    context = =>
+      data = {}
+
+      if isResource
+        Joosy.Module.merge data, stack.locals.data
+      else
+        Joosy.Module.merge data, stack.locals
+
+      Joosy.Module.merge data, @__instantiateHelpers(), false
+      Joosy.Module.merge data, renderers
+      data
+
+    result = -> template(context())
+
+    if dynamic
+      morph  = Metamorph result()
+      update = =>
+        if morph.isRemoved()
+          for [object, callback] in morph.__bindings
+            object.unbind callback
+        else
+          for child in stack.children
+            @__removeMetamorphs child
+          stack.children = []
+          morph.html result()
+          @refreshElements?()
+
+      # This is here to break stack tree and save from
+      # repeating DOM handling
+      update = update.debounce 0
+
+      morph.__bindings = []
+
+      if isCollection
+        for resource in locals.data
+          binding = [resource, update]
+          resource.bind 'changed', update
+          stack.metamorphBindings.push binding
+          morph.__bindings.push binding
+      if isResource || isCollection
+        binding = [locals, update]
+        locals.bind 'changed', update
+        stack.metamorphBindings.push binding
+        morph.__bindings.push binding
+      else
+        for key, object of locals
+          if locals.hasOwnProperty key
+            if object?.bind? && object?.unbind?
+              binding = [object, update]
+              object.bind 'changed', update
+              stack.metamorphBindings.push binding
+              morph.__bindings.push binding
+
+      morph.outerHTML()
+    else
+      result()
+
+  __renderingStackElement: (parent=null) ->
+    metamorphBindings: []
+    locals: null
+    template: null
+    children: []
+    parent: parent
+
+  __renderingStackChildFor: (parentPointer) ->
+    if !@__renderingStack
+      @__renderingStack = []
+
+    if !parentPointer
+      element = @__renderingStackElement()
+      @__renderingStack.push element
+      element
+    else
+      element = @__renderingStackElement parentPointer
+      parentPointer.children.push element
+      element
+
+  __removeMetamorphs: (stackPointer=false) ->
+    remove = (stackPointer) =>
+      if stackPointer?.children
+        for child in stackPointer.children
+          @__removeMetamorphs child
+
+      if stackPointer?.metamorphBindings
+        for [object, callback] in stackPointer.metamorphBindings
+          object.unbind callback
+        stackPointer.metamorphBindings = []
+
+    unless stackPointer
+      @__renderingStack?.each (stackPointer) ->
+        remove stackPointer
+    else
+      remove stackPointer

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

@@ -0,0 +1,46 @@
+#
+# Comfortable and clever wrappers for timeouts management
+#
+# @mixin
+#
+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 ||= []
+
+    timer = window.setTimeout (=> action()), timeout
+    @__timeouts.push timer
+
+    timer
+
+  #
+  # Registeres interval for current object
+  #
+  # @param [Integer] delay            Miliseconds between runs
+  # @param [Function] action          Action to run
+  #
+  setInterval: (delay, action) ->
+    @__intervals ||= []
+
+    timer = window.setInterval (=> action()), delay
+    @__intervals.push timer
+
+    timer
+
+  #
+  # Drops all registered timeouts and intervals for this object
+  #
+  __clearTime: ->
+    if @__intervals
+      for entry in @__intervals
+        window.clearInterval entry
+
+    if @__timeouts
+      for entry in @__timeouts
+        window.clearTimeout entry

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

@@ -0,0 +1,87 @@
+#
+# Widgets management routines
+#
+# @mixin
+#
+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()
+
+    if Object.isFunction(widget)
+      widget = widget()
+
+    @__activeWidgets ||= []
+    @__activeWidgets.push widget.__load(this, $(container))
+
+    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 || {}
+
+    klass = this
+    while klass = klass.constructor.__super__
+      Joosy.Module.merge widgets, klass.widgets, false
+
+    widgets
+
+  #
+  # Intialize all widgets for current object
+  #
+  __setupWidgets: ->
+    widgets    = @__collectWidgets()
+    registered = Object.extended()
+
+    widgets.each (selector, widget) =>
+      if selector == '$container'
+        activeSelector = @container
+      else
+        if r = selector.match /\$([A-z_]+)/
+          selector = @elements[r[1]]
+
+        activeSelector = $(selector, @container)
+
+      registered[selector] = Object.extended()
+
+      activeSelector.each (index, elem) =>
+        if Joosy.Module.hasAncestor widget, Joosy.Widget
+          instance = new widget
+        else
+          instance = widget.call this, index
+
+        registered[selector][Joosy.Module.__className instance] ||= 0
+        registered[selector][Joosy.Module.__className instance]  += 1
+
+        @registerWidget $(elem), instance
+
+    registered.each (selector, value) =>
+      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
+        widget.__unload()

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

@@ -0,0 +1,387 @@
+#= require joosy/core/joosy
+#= require joosy/core/modules/module
+#= require joosy/core/modules/log
+#= require joosy/core/modules/events
+#= require joosy/core/modules/container
+#= require joosy/core/modules/renderer
+#= require joosy/core/modules/time_manager
+#= 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'
+#
+# @include Joosy.Modules.Log
+# @include Joosy.Modules.Events
+# @include Joosy.Modules.Container
+# @include Joosy.Modules.Renderer
+# @include Joosy.Modules.TimeManager
+# @include Joosy.Modules.WidgetsManager
+# @include Joosy.Modules.Filters
+#
+class Joosy.Page extends Joosy.Module
+  @include Joosy.Modules.Log
+  @include Joosy.Modules.Events
+  @include Joosy.Modules.Container
+  @include Joosy.Modules.Renderer
+  @include Joosy.Modules.TimeManager
+  @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
+
+  #
+  # 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
+
+  #
+  # Scrolls page to stored positions
+  #
+  __performScrolling: ->
+    scroll = $(@__extractSelector @__scrollElement).offset()?.top + @__scrollMargin
+    Joosy.Modules.Log.debugAs @, "Scrolling to #{@__extractSelector @__scrollElement}"
+    $('html, body').animate {scrollTop: scroll}, @__scrollSpeed, =>
+      if @__scrollSpeed != 0
+        @__releaseHeight()
+
+  #
+  # 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
+      if !@previous?.layout?.uuid? || @previous?.__layoutClass != @__layoutClass
+        @__bootstrapLayout()
+      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}
+  #   * Scrolling
+  #
+  __load: ->
+    @refreshElements()
+    @__delegateEvents()
+    @__setupWidgets()
+    @__runAfterLoads @params, @previous
+    @__performScrolling() if @__scrollElement
+    Joosy.Application.loading = false
+    Joosy.Router.trigger 'loaded', this
+    @trigger 'loaded'
+
+    Joosy.Modules.Log.debugAs @, "Page loaded"
+
+  #
+  # Page destruction proccess.
+  #
+  #   * {Joosy.Modules.TimeManager.__clearTime}
+  #   * {Joosy.Modules.WidgetsManager.__unloadWidgets}
+  #   * {Joosy.Modules.Renderer.__removeMetamorphs}
+  #
+  __unload: ->
+    @__clearTime()
+    @__unloadWidgets()
+    @__removeMetamorphs()
+    @__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()
+
+  #
+  # The single page (without layout reloading) bootstrap logic
+  #
+  # @example Hacky boot sequence description
+  #   previous::erase  \
+  #   previous::unload  \
+  #   beforePaint        \
+  #                       > paint
+  #   fetch             /
+  #
+  __bootstrap: ->
+    Joosy.Modules.Log.debugAs @, "Boostraping page"
+    @layout = @previous.layout
+
+    callbacksParams = [@layout.content()]
+
+    if @__scrollElement && @__scrollSpeed != 0
+      @__fixHeight()
+
+    @wait "stageClear dataReceived", =>
+      @__callSyncedThrough this, '__paint', callbacksParams, =>
+        # Page HTML
+        @swapContainer @layout.content(), @__renderer(@data || {})
+        @container = @layout.content()
+
+        # Loading
+        @__load()
+
+        @layout.content()
+
+    @__callSyncedThrough @previous, '__erase', callbacksParams, =>
+      @previous?.__unload()
+      @__callSyncedThrough this, '__beforePaint', callbacksParams, =>
+        @trigger 'stageClear'
+
+    @__callSyncedThrough this, '__fetch', [], =>
+      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)
+
+    callbacksParams = [Joosy.Application.content(), this]
+
+    if @__scrollElement && @__scrollSpeed != 0
+      @__fixHeight()
+
+    @wait "stageClear dataReceived", =>
+      @__callSyncedThrough @layout, '__paint', callbacksParams, =>
+        # Layout HTML
+        data = Joosy.Module.merge {}, @layout.data || {}
+        data = Joosy.Module.merge data, yield: => @layout.yield()
+
+        @swapContainer Joosy.Application.content(), @layout.__renderer data
+
+        # Page HTML
+        @swapContainer @layout.content(), @__renderer(@data || {})
+        @container = @layout.content()
+
+        # Loading
+        @layout.__load Joosy.Application.content()
+        @__load()
+
+        Joosy.Application.content()
+
+    @__callSyncedThrough @previous?.layout, '__erase', callbacksParams, =>
+      @previous?.layout?.__unload?()
+      @previous?.__unload()
+      @__callSyncedThrough @layout, '__beforePaint', callbacksParams, =>
+        @trigger 'stageClear'
+
+    @__callSyncedThrough @layout, '__fetch', [], =>
+      @__callSyncedThrough this, '__fetch', [], =>
+        Joosy.Modules.Log.debugAs @, "Fetch complete"
+        @trigger 'dataReceived'