joosy 0.1.0.RC1 → 0.1.0.RC2

data/Gemfile

@@ -5,6 +5,7 @@ gemspec
 
 gem 'jasmine',         :git => 'git://github.com/pivotal/jasmine-gem.git'
 gem 'guard-sprockets', :git => 'git://github.com/roundlake/guard-sprockets.git'
+gem 'thin'
 
 group :test do
   if RUBY_PLATFORM =~ /linux/

data/Gemfile.lock

@@ -19,7 +19,7 @@ GIT
 PATH
   remote: .
   specs:
-    joosy (0.1.0.alpha)
+    joosy (0.1.0.RC1)
       coffee-rails
       haml_coffee_assets
       jquery-rails
@@ -66,8 +66,10 @@ GEM
       coffee-script-source
       execjs
     coffee-script-source (1.2.0)
+    daemons (1.1.8)
     diff-lcs (1.1.3)
     erubis (2.7.0)
+    eventmachine (0.12.10)
     execjs (1.3.0)
       multi_json (~> 1.0)
     ffi (1.0.11)
@@ -140,6 +142,10 @@ GEM
       hike (~> 1.2)
       rack (~> 1.0)
       tilt (~> 1.1, != 1.3.0)
+    thin (1.3.1)
+      daemons (>= 1.0.9)
+      eventmachine (>= 0.12.6)
+      rack (>= 1.0.0)
     thor (0.14.6)
     tilt (1.3.3)
     treetop (1.4.10)
@@ -157,3 +163,4 @@ DEPENDENCIES
   guard-sprockets!
   jasmine!
   joosy!
+  thin

data/MIT-LICENSE

@@ -1,5 +1,5 @@
-Copyright (C) 2011 by Boris Staal <boris@roundlake.ru>,
-                      Peter Zotov <p.zotov@roundlake.ru>.
+Copyright (C) 2011, 2012 by Boris Staal <boris@roundlake.ru>,
+                            Peter Zotov <p.zotov@roundlake.ru>.
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -0,0 +1,89 @@
+![Joosy](http://f.cl.ly/items/2N2J453J2B353F1A0t0I/joocy1.1.png)
+
+## What is Joosy
+
+Joosy is a full-featured javascript MVC framework, which mostly follows Rails philosophy, particularly in preferring conventions over configuration. It helps you to avoid boilerplate and makes it easy to maintain and extend the app.
+
+Joosy allows you to create web apps which work completely in the browser. So that, it helps you to relocate all your Rails Views to the client side. It also helps you with managing the growing quantity of JS code. On another hand, it makes your backend to have exactly one function --  to be a simple REST provider. That leads to easier development support and improves the scalability greatly.
+
+Joosy doesn't compete with jQuery. It is built on the top of [jQuery](http://jquery.com/), and utilizes [CoffeeScript](http://coffeescript.org/). It either includes [Sugar.js](http://sugarjs.com/) in role of ActiveSupport to make your life even better.
+
+Finally, Joosy boosts your development drastically.
+
+### How is Joosy different from X
+
+We share quite different goals and totally differ in ways to achieve it. While existing MVC frameworks define basic entities for you and leave you alone with application basic patterns and solutions, Joosy tries to give convention for each of them.
+
+#### [Backbone](http://documentcloud.github.com/backbone/)
+
+In Backbone or Spine you only have abstract Views, Models and "Packs of …" and you should even decide on your own what's Controller for you. Joosy gives you the ready plan on how to move on to the success. If you ever used Rails you know that feeling: you concentrate on _what_ you create and not on _how_ to structure it.
+
+#### [Ember](http://emberjs.com/)
+
+Ember is the closest framework by spirit. But it still doesn't give you enough conventions and is even more abstract than Backbone in several parts. It either limits you to Handlebars. Joosy rendering system is built on top of same solution, Morpher. That said you can bind your variables dynamically just like in Ember. But it allows you to any templates syntax.
+
+### The Joosy MVC Interpretation
+
+You probably are familiar with the concept of MVC. It's a pattern to keep code DRY, isolate business logic from the UI. However the concept of Model-View-Controller just doesn't work for browser applications. There are numerous reasons for that that can't be fit into this introduction. Instead we'll tell you what we propose.
+
+#### Views
+
+In Joosy views are just views. Set of files (in templates/ folder). They do not differ from Rails and give you quite the same abilities (including helpers!). Besides that Joosy has renderDynamic which allows you to bind your variables to HTML representation tightly. You change variable value, Joosy changes HTML.
+
+By default Joosy comes with Coffee-Haml (which looks and works pretty much like Ruby Haml). Combined with Sugar.js it will feel very similar to Ruby and server-side and will provide you the easiest migration.
+
+#### Controllers
+
+Unlike server-side, client-side has a state. At server-side you only have incoming data and you convert it to output data. At client-side you work with events. To handle correct bootstrap and help you organize your code well, we have 3 entities which play the role of controller. Their organizing functions are similar but they behavior dramatically different at bootstrap.
+
+They are:
+
+##### Pages
+Pages are the heart of the entire application. They are used to fetch data, bind events, setup widgets, trig visual effects, and pass the data to the templates.
+
+##### Layouts 
+Layouts are mainly used to set a part of your page that won't be reloaded often. Pages are wrapped into Layouts. Just like pages Layouts can bind events and setup widgets. Consider layouts as a bit extended version of what you have in Rails.
+
+##### Widgets 
+Widgets are needed to keep your code DRY. They help you organize it in reusable modules.
+
+#### Models
+
+There are some facts that should be noted to explain it how we understand browser-side models.
+
+* In most cases you will want to leave your logic on server-side. In a real models. 
+* You rarely want to make 5 HTTP requests instead of 1.
+* In most cases you will have to give user a Form as a way to change anything.
+* You'll get different possible set of fields depending on case you use your model at.
+
+With all that in mind we came up to the fact: you can not reproduce real models in browser nor you should try to. What you need is a comfortable channel between browser and server-side to get structured data, work with that and send it back. That's mainly a transport and interface task while models are MUCH more than that. To solve this task Joosy offers you two things:
+
+###### Resources
+Resource is wrapper on top of JSON dump which will help you to get data from server, parse it and structure it. It will trigger 'changed' if you change resource, will map inline hashes in other resources if possible and do all other magic stuff you expect from your model when you read data. Resources either define Collections. In most cases you can say Resources are fully-functional read part of what you get used to as model.
+
+###### Forms
+After you got your data as resources and used it to display something, you'll need to change it. While resource defines modification methods like _save_ and _destroy_ most of complex modifications should go through Joosy.Form. It turns your form into AJAX and binds the resource to it. It handles file uploads, it gives you upload progress callback and makes it a dream to handle. Joosy.Form will either understand standard Rails invalidation response and will mark invalidated fields with ".field_with_errors" out of box.
+
+
+## What is Joosy good for
+
+Joosy is intended to ease building of modern medium and large-sized browser-based applications, minimize code base while providing more features and what's most important, giving you ready conventions for typical tasks.
+
+Compare Joosy to Backbone like Rails to Sinatra. While Rails engine is much more powerful, Sinatra still has a lot of cases to be used at. If all you need is to enable some RICHness on one of your pages, Joosy can handle that. But Backbone will do the trick with lesser dependencies. If you need to move complete web-resource to browser Joosy will do the task at its Best.
+
+## What's next?
+
+We have a set of guidelines showing you, step-by-step, how to create a Joosy application. You should probably follow them starting from [Creating a new project](http://roundlake.github.com/joosy/guides/creating-a-new-project.html)
+
+### Hello world app
+
+Using built-in generators you can quickly generate small app inside your Rails app to see Joosy application from inside a bit.
+
+    rails g joosy:application dummy
+    rails g joosy:preloader dummy
+
+Now you can `rails s` and see Joosy placeholder at [localhost:3000/dummy](http://localhost:3000/dummy)
+
+# License
+
+Joosy is licensed under MIT: [www.opensource.org/licenses/MIT](www.opensource.org/licenses/MIT)

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

@@ -1,28 +1,48 @@
 #= require joosy/core/joosy
 
+#
+# Joosy Application container
+#
 Joosy.Application =
   Pages: {}
   Layouts: {}
   Controls: {}
 
-  selector: false
-
+  #
+  # Starts Joosy application by binding to element and bootstraping routes
+  #
+  # @param [String] name        Name of app (the dir its located in)
+  # @param [String] selector    jQuery-compatible selector of root application element
+  # @param [Object] options
+  #
   initialize: (@name, @selector, options={}) ->
     @[key] = value for key, value of options
-    @templater = new Joosy.Templaters.RailsJST(@name)
+    @templater = new Joosy.Templaters.RailsJST @name
 
     Joosy.Router.setupRoutes()
 
     @sandboxSelector = Joosy.uuid()
-    @content().after("<div id='#{@sandboxSelector}' style='display:none'></div>")
+    @content().after "<div id='#{@sandboxSelector}' style='display:none'></div>"
     @sandboxSelector = '#' + @sandboxSelector
 
+  #
+  # Gets current application root node
+  #
   content: ->
     $(@selector)
 
+  #
+  # Gets current application sandbox node
+  #
   sandbox: ->
     $(@sandboxSelector)
 
+  #
+  # Switches to given page
+  #
+  # @param [Joosy.Page] page      The class (not object) of page to load
+  # @param [Object] params        Hash of page params
+  #
   setCurrentPage: (page, params) ->
     #if @page not instanceof page
-    @page = new page(params, @page)
+    @page = new page params, @page

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

@@ -4,84 +4,274 @@
 #= require joosy/core/modules/events
 #= require joosy/core/modules/container
 
+#
+# AJAXifies form including file uploads and stuff. Built on top of jQuery.Form
+#
+# Joosy.Form automatically cares of form validation hihglights. It can
+# read common server error responses and add .field_with_errors class to proper 
+# field.
+#
+# If you don't have resource associated (#fill) with form it will try to find fields
+# by exact keywords from response. Otherwise it will search for resource_name[field].
+#
+#
+# Example
+#   form = new Joosy.Form, -> (response)
+#     console.log "Saved and got some: #{response}"
+#
+#   form.progress = (percent) -> console.log "Uploaded by #{percent}%"
+#   form.fill @resource
+#
 class Joosy.Form extends Joosy.Module
   @include Joosy.Modules.Log
   @include Joosy.Modules.Events
   @include Joosy.Modules.Container
 
+  #
+  # Marks the CSS class to use to mark invalidated fields
+  #
   invalidationClass: 'field_with_errors'
+  
+  #
+  # List of mappings for fields of invalidated data which comes from server
+  #
+  # If you have something like {foo: 'bar', bar: 'baz'} coming from server
+  # substitutions = {foo: 'foo_id'} will change it to {foo_id: 'bar', bar: 'baz'}
+  #
   substitutions: {}
 
+  #
+  # List of elements for internal usage
+  #
   elements:
     'fields': 'input,select,textarea'
 
+  #
+  # Submits your form once and unbinds leaving it simple form without AJAX
+  #
+  # @param [Element] form       Instance of HTML form element
+  # @param [Object] opts        Map of additional options (see constructor)
+  #
+  @submit: (form, opts={}) ->
+    form = new @(form, opts)
+    form.container.submit()
+    form.unbind()
+    null
+
+  #
+  # During initialization replaces your basic form submit with AJAX request
+  #
+  # If method of form differs from POST or GET it will simulate it
+  # by adding hidden _method input. In this cases the method itself will be
+  # set to POST.
+  #
+  # For browsers having no support of HTML5 Forms it may do an iframe requests
+  # to handle file uploading.
+  #
+  # Supported options are:
+  #
+  # * before: `(XHR) -> Boolean` triggers right before submit.
+  #   By default will run form invalidation cleanup. This behavior can be canceled
+  #   by returning false from your own before callback. Both of callbacks will run if
+  #   you return true.
+  #
+  # * success: `(Object) -> null` triggers on 200 HTTP code from server. Pases 
+  #   in the parsed JSON.
+  #
+  # * progress: `(Float) -> null` runs peridically while form is uploading.
+  #
+  # * error: `(Object) -> Boolean` triggers if server responsed with anything but 200.
+  #   By default will run form invalidation routine. This behavior can be canceled
+  #   by returning false from your own error callback. Both of callbacks will run if
+  #   you return true.
+  # 
+  #
   constructor: (form, opts={}) ->
     if Object.isFunction opts
       @success = opts
     else
-      Object.extended(opts).each (key, value) =>
+      Object.each opts, (key, value) =>
         @[key] = value
 
     @container = $(form)
     @refreshElements()
     @__delegateEvents()
 
-    if (method = @container.get(0).getAttribute('method')?.toLowerCase()) && !['get', 'post'].has(method)
+    method = @container.get(0).getAttribute('method')?.toLowerCase()
+    if method && !['get', 'post'].has method
       @__markMethod method
       @container.attr 'method', 'POST'
 
     @container.ajaxForm
       dataType: 'json'
-      beforeSend: => @__before(arguments...)
-      success: => @__success(arguments...)
-      error: => @__error(arguments...)
+      beforeSend: =>
+        @__before arguments...
+      success: =>
+        @__success arguments...
+      error: =>
+        @__error arguments...
       xhr: =>
         xhr = $.ajaxSettings.xhr()
         if xhr.upload? && @progress
           xhr.upload.onprogress = (event) =>
-            @progress (event.position/event.total*100).round(2) if event.lengthComputable
+            if event.lengthComputable
+              @progress (event.position / event.total * 100).round 2
         xhr
 
+  #
+  # Resets form submit behavior
+  #
+  unbind: ->
+    @container.unbind('submit').find('input:submit,input:image,button:submit').unbind('click');
+
+  #
+  # Sets values of form inputs from given resource.
+  # Form will remember given resource and will use it while doing
+  # invalidation routine.
+  #
+  # @param [Resource] resource      Resource to fill fields with
+  # @param [Function] decorator     Decoration callback
+  #
   fill: (resource, decorator) ->
-    e = if decorator? then decorator(resource.e) else resource.e
+    @__resource = resource
+    
+    if decorator?
+      e = decorator resource.e
+    else
+      e = resource.e
     Object.each e, (key, val) =>
-      key = resource.constructor.entityName()+"[#{key}]"
-      @fields.filter("[name='#{key.underscore()}']:not(:file),[name='#{key.camelize(false)}']:not(:file)").val(val)
+      key = resource.__entityName + "[#{key}]"
+      input = @fields.filter("[name='#{key.underscore()}']:not(:file),[name='#{key.camelize(false)}']:not(:file)")
+      unless input.is ':checkbox'
+        input.val val
+      else
+        if val
+          input.attr 'checked', 'checked'
+        else
+          input.removeAttr 'checked'
 
     @container.attr 'action', resource.constructor.__buildSource(extension: resource.id)
     @__markMethod() if resource.id
     @container.attr 'method', 'POST'
 
+  #
+  # Inner success callback
+  #
   __success: (response, status, xhr) ->
     if xhr
-      @success(response)
+      @success? response
     else if response.status == 200
-      @success(response.json)
+      @success response.json
     else
-      @__error(response.json)
+      @__error response.json
 
+  #
+  # Inner before callback
+  # By default will clean invalidation
+  #
   __before: (xhr, settings) ->
     if !@before? || @before(arguments...) is true
-      @fields.removeClass(@invalidationClass)
+      @fields.removeClass @invalidationClass
 
+  #
+  # Inner error callback
+  # By default will trigger basic invalidation
+  #
   __error: (data) ->
     errors = if data.responseText
       try
-        Object.extended(jQuery.parseJSON(data.responseText))
+        data = jQuery.parseJSON(data.responseText)
       catch error
-        Object.extended()
+        {}
     else
-      Object.extended(data)
+      data
 
     if !@error? || @error(errors) is true
-      errors.each (field, notifications) =>
-        field = @substitutions[field] if @substitutions[field]?
-        input = @fields.filter("[name='#{field}']").addClass(@invalidationClass)
-        @notification?(input, notifications)
+      errors = @__stringifyErrors(errors)
+      
+      Object.each errors, (field, notifications) =>
+        input = @fields.filter("[name='#{field}']").addClass @invalidationClass
+        @notification? input, notifications
 
+  #
+  # Simulates REST methods by adding hidden _method input with real method
+  # while setting POST as the transport method
+  #
+  # @param [String] method      Real method to simulate
+  #
   __markMethod: (method='PUT') ->
-    method = $ '<input/>',
+    method = $('<input/>',
       type: 'hidden'
       name: '_method'
       value: method
-    @container.append(method)
+    )
+    @container.append method
+    
+  #
+  # Prepares server response for default error handler
+  # Turns all possible response notations into form notation (foo[bar])
+  # Every direct field of incoming data will be decorated by @substitutions
+  #
+  # Possible notations:
+  #
+  # * Flat validation result
+  #   # input
+  #   { field1: ['error'] }
+  #   # if form was not associated with @__resource (see #fill)
+  #   { "field1": ['error'] }
+  #   # if form was associated with resource (named fluffy)
+  #   { "fluffy[field1]": ['error']}
+  #
+  # * Complex validation result
+  #   # input
+  #   { foo: { bar: { baz: ['error'] } } }
+  #   # output
+  #   { "foo[bar][bar]": ['error'] }
+  #
+  # @param [Object] errors        Data to prepare
+  #
+  __stringifyErrors: (errors) ->
+    result = {}
+    
+    Object.each errors, (field, notifications) =>
+      if @substitutions[field]?
+        field = @substitutions[field]
+
+      if Object.isObject notifications
+        Object.each @__foldInlineEntities(notifications), (key, value) ->
+          result[field+key] = value
+      else
+        if field.indexOf(".") != -1
+          splited = field.split '.'
+          field   = splited.shift()
+          field   = @__resource.__entityName + "[#{field}]" if @__resource
+          field  += "[#{f}]" for f in splited
+      
+        else if @__resource
+          field = @__resource.__entityName + "[#{field}]"
+
+        result[field] = notifications
+
+    result
+
+  #
+  # Flattens complex inline structures into form notation
+  #
+  # Example:
+  #   data  = foo: { bar: { baz: [] } }
+  #   inner = @__foldInlineEntities(data.foo, 'foo')
+  #
+  #   inner # { "foo[bar][baz]": [] }
+  #
+  # @param [Object] hash      Structure to fold
+  # @param [String] scope     Prefix for resulting scopes
+  # @param [Object] result    Context of result for recursion
+  #
+  __foldInlineEntities: (hash, scope="", result={}) ->
+    Object.each hash, (key, value) =>
+      if Object.isObject(value)
+        @__foldInlineEntities(value, "#{scope}[#{key}]", result)
+      else
+        result["#{scope}[#{key}]"] = value
+
+    result

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

@@ -1,6 +1,16 @@
 #= require joosy/core/joosy
 
+#
+# Set of system-wide helpers built-in into Joosy
+#
+# @class Joosy.Helpers.Application
+#
 Joosy.helpers 'Application', ->
   
+  #
+  # Converts \n into <br/> in your text
+  #
+  # @param [String] text      Text to convert
+  #
   @nl2br = (text) ->
-    text.toString().replace(/\n/g, '<br/>')
+    text.toString().replace /\n/g, '<br/>'

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

@@ -1,24 +1,24 @@
-@Joosy = Object.extended(if @Joosy? then @Joosy else {})
-
-@Joosy.merge
+@Joosy = Object.extended
   debug: false
   Modules: {}
   Resource: {}
   Templaters: {}
 
 Joosy.namespace = (name, generator=false) ->
-  name  = name.split('.')
+  name  = name.split '.'
   space = window
-  space = space[part] ?= {} for part in name
+  for part in name
+    space = space[part] ?= {}
 
-  generator = generator.apply(space) if generator
+  if generator
+    generator = generator.apply space
   for key, klass of space
     if space.hasOwnProperty(key) &&
-          Joosy.Module.hasAncestor(klass, Joosy.Module)
+       Joosy.Module.hasAncestor klass, Joosy.Module
       klass.__namespace__ = name
 
 Joosy.helpers = (name, generator) ->
-  Joosy.namespace("Joosy.Helpers.#{name}", generator)
+  Joosy.namespace "Joosy.Helpers.#{name}", generator
 
 Joosy.test = ->
   text = "Hi :). I'm Joosy. And everything is just fine!"
@@ -36,13 +36,16 @@ Joosy.uuid = ->
   .toUpperCase()
 
 Joosy.preloadImages = (images, callback) ->
-  images = [images] if !Object.isArray(images)
-  callback() if images.length == 0
+  unless Object.isArray(images)
+    images = [images]
+  if images.length == 0
+    callback()
 
   ticks   = images.length
   result  = []
   checker = ->
-    callback?() if (ticks -= 1) == 0
+    if (ticks -= 1) == 0
+      callback?()
 
   for p in images
     result.push $('<img/>').load(checker).attr('src', p)
@@ -53,13 +56,15 @@ Joosy.buildUrl = (url, params) ->
   paramsString = []
 
   Object.each params, (key, value) ->
-    paramsString.push("#{key}=#{value}")
+    paramsString.push "#{key}=#{value}"
 
   hash = url.match(/(\#.*)?$/)[0]
-  url  = url.replace(/\#.*$/, '')
-  url  = url + "?" if !paramsString.isEmpty() && !url.has(/\?/)
+  url  = url.replace /\#.*$/, ''
+  if !paramsString.isEmpty() && !url.has(/\?/)
+    url  = url + "?"
 
-  paramsString = paramsString.join('&')
-  paramsString = '&' + paramsString if paramsString != '' && url.last() != '?'
+  paramsString = paramsString.join '&'
+  if !paramsString.isBlank() && url.last() != '?'
+    paramsString = '&' + paramsString
 
-  url + paramsString + hash
+  url + paramsString + hash

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

@@ -17,11 +17,21 @@ class Joosy.Layout extends Joosy.Module
   @include Joosy.Modules.WidgetsManager
   @include Joosy.Modules.Filters
 
-  @view 'layouts/default'
-
-  @beforePaint: (callback) -> @::__beforePaint = callback
-  @paint: (callback) -> @::__paint = callback
-  @erase: (callback) -> @::__erase = callback
+  @view 'default'
+
+  @beforePaint: (callback) ->
+    @::__beforePaint = callback
+  @paint: (callback) ->
+    @::__paint = callback
+  @erase: (callback) ->
+    @::__erase = callback
+    
+  @fetch: (callback) ->
+    @::__fetch = callback
+
+  data: false
+  
+  constructor: (@params) ->
 
   navigate: (args...) ->
     Joosy.Router.navigate(args...)
@@ -36,7 +46,7 @@ class Joosy.Layout extends Joosy.Module
     @__runAfterLoads()
 
   __unload: ->
-    @clearTime()
+    @__clearTime()
     @__unloadWidgets()
     @__runAfterUnloads()
 
@@ -44,4 +54,4 @@ class Joosy.Layout extends Joosy.Module
     @uuid = Joosy.uuid()
 
   content: ->
-    $("##{@uuid}")
+    $("##{@uuid}")