joosy 0.1.0.RC2 → 0.1.0.RC3

data/.codoopts

@@ -0,0 +1,5 @@
+--readme	README.md
+--title		"Joosy API"
+--verbose
+--output-dir	./doc
+./app

data/.gitignore

@@ -3,3 +3,5 @@
 log/*.log
 pkg/
 tmp/
+.DS_Store
+doc/

data/Gemfile.lock

@@ -19,7 +19,7 @@ GIT
 PATH
   remote: .
   specs:
-    joosy (0.1.0.RC1)
+    joosy (0.1.0.RC2)
       coffee-rails
       haml_coffee_assets
       jquery-rails
@@ -70,6 +70,7 @@ GEM
     diff-lcs (1.1.3)
     erubis (2.7.0)
     eventmachine (0.12.10)
+    eventmachine (0.12.10-java)
     execjs (1.3.0)
       multi_json (~> 1.0)
     ffi (1.0.11)
@@ -80,7 +81,7 @@ GEM
     guard-coffeescript (0.5.4)
       coffee-script (>= 2.2.0)
       guard (>= 0.8.3)
-    haml_coffee_assets (0.7.1)
+    haml_coffee_assets (0.8.2)
       execjs (>= 1.2.9)
       sprockets (>= 2.0.3)
       tilt (>= 1.3.3)
@@ -92,6 +93,7 @@ GEM
       railties (>= 3.2.0.beta, < 5.0)
       thor (~> 0.14)
     json (1.6.5)
+    json (1.6.5-java)
     mail (2.4.1)
       i18n (>= 0.4.0)
       mime-types (~> 1.16)

data/README.md

@@ -38,13 +38,13 @@ Unlike server-side, client-side has a state. At server-side you only have incomi
 
 They are:
 
-##### Pages
+###### 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 
 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 
 Widgets are needed to keep your code DRY. They help you organize it in reusable modules.
 
 #### Models
@@ -73,10 +73,14 @@ Compare Joosy to Backbone like Rails to Sinatra. While Rails engine is much more
 
 ## 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)
+We have a set of guidelines showing you, step-by-step, how to create a Joosy application. Follow them at our [Guides site](http://guides.joosy.ws/).
 
 ### Hello world app
 
+Add Joosy gem to your Gemfile:
+
+    gem 'joosy'
+
 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
@@ -84,6 +88,8 @@ Using built-in generators you can quickly generate small app inside your Rails a
 
 Now you can `rails s` and see Joosy placeholder at [localhost:3000/dummy](http://localhost:3000/dummy)
 
+Generated application will consist of one `Layout` and one `Page` both including very basic practices of Joosy.
+
 # 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

@@ -7,6 +7,8 @@ Joosy.Application =
   Pages: {}
   Layouts: {}
   Controls: {}
+  
+  loading: true
 
   #
   # Starts Joosy application by binding to element and bootstraping routes
@@ -19,7 +21,7 @@ Joosy.Application =
     @[key] = value for key, value of options
     @templater = new Joosy.Templaters.RailsJST @name
 
-    Joosy.Router.setupRoutes()
+    Joosy.Router.__setupRoutes()
 
     @sandboxSelector = Joosy.uuid()
     @content().after "<div id='#{@sandboxSelector}' style='display:none'></div>"

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

@@ -5,20 +5,19 @@
 #= require joosy/core/modules/container
 
 #
-# AJAXifies form including file uploads and stuff. Built on top of jQuery.Form
+# 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
+# If you don't have resource associated with form (#fill), it will try to find fields
 # by exact keywords from response. Otherwise it will search for resource_name[field].
 #
-#
-# Example
+# @example Joosy.Form usage
 #   form = new Joosy.Form, -> (response)
 #     console.log "Saved and got some: #{response}"
-#
+#   
 #   form.progress = (percent) -> console.log "Uploaded by #{percent}%"
 #   form.fill @resource
 #
@@ -47,10 +46,12 @@ class Joosy.Form extends Joosy.Module
     'fields': 'input,select,textarea'
 
   #
-  # Submits your form once and unbinds leaving it simple form without AJAX
+  # Makes one AJAX request with form data without binding
+  #
+  # @see #constructor
   #
   # @param [Element] form       Instance of HTML form element
-  # @param [Object] opts        Map of additional options (see constructor)
+  # @param [Hash] opts          Options
   #
   @submit: (form, opts={}) ->
     form = new @(form, opts)
@@ -61,30 +62,30 @@ class Joosy.Form extends Joosy.Module
   #
   # During initialization replaces your basic form submit with AJAX request
   #
-  # If method of form differs from POST or GET it will simulate it
+  # @note 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
+  # @note For browsers having no support of HTML5 Forms it may do an iframe requests
   # to handle file uploading.
   #
-  # Supported options are:
+  # @param [jQuery] form        Form element instance
+  # @param [Hash] opts          Options
   #
-  # * before: `(XHR) -> Boolean` triggers right before submit.
+  # @option opts [Function] before        `(XHR) -> Bollean` to trigger 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.
+  # @option opts [Function] success       `(Object) -> null` triggers on 200 HTTP code from server. 
+  #   Pases in the parsed JSON.
   #
-  # * progress: `(Float) -> null` runs peridically while form is uploading.
+  # @option opts [Function] progress      `(Float) -> null` runs periodically while form is uploading
   #
-  # * error: `(Object) -> Boolean` triggers if server responsed with anything but 200.
+  # @option opts [Function] error         `(Object) -> Boolean` triggers if server responded 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
@@ -119,15 +120,14 @@ class Joosy.Form extends Joosy.Module
         xhr
 
   #
-  # Resets form submit behavior
+  # Resets form submit behavior to default
   #
   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.
+  # Links current form with given resource and sets values of form inputs from with it.
+  # Form will use give resource while doing invalidation routine.
   #
   # @param [Resource] resource      Resource to fill fields with
   # @param [Function] decorator     Decoration callback
@@ -155,7 +155,26 @@ class Joosy.Form extends Joosy.Module
     @container.attr 'method', 'POST'
 
   #
-  # Inner success callback
+  # Submit the HTML Form
+  #
+  submit: ->
+    @container.submit()
+  
+  #
+  # Serializes form into query string.
+  #
+  # @param [Boolean] skipMethod         Determines if we should skip magical _method field
+  #
+  # @return [String]
+  #
+  serialize: (skipMethod=true) ->
+    data = @container.serialize()
+    data = data.replace /\&?\_method\=put/i, '' if skipMethod
+    
+    data
+
+  #
+  # Inner success callback.
   #
   __success: (response, status, xhr) ->
     if xhr
@@ -166,16 +185,16 @@ class Joosy.Form extends Joosy.Module
       @__error response.json
 
   #
-  # Inner before callback
-  # By default will clean invalidation
+  # Inner before callback.
+  # By default will clean invalidation.
   #
   __before: (xhr, settings) ->
     if !@before? || @before(arguments...) is true
       @fields.removeClass @invalidationClass
 
   #
-  # Inner error callback
-  # By default will trigger basic invalidation
+  # Inner error callback.
+  # By default will trigger basic invalidation.
   #
   __error: (data) ->
     errors = if data.responseText
@@ -190,8 +209,18 @@ class Joosy.Form extends Joosy.Module
       errors = @__stringifyErrors(errors)
       
       Object.each errors, (field, notifications) =>
-        input = @fields.filter("[name='#{field}']").addClass @invalidationClass
+        input = @__findField(field).addClass @invalidationClass
         @notification? input, notifications
+  
+  #
+  # Finds field by field name.
+  # This is not inlined since we want to override
+  # or monkeypatch it from time to time
+  #
+  # @param [String] field         Name of field to find
+  #
+  __findField: (field) ->
+    @fields.filter("[name='#{field}']")
 
   #
   # Simulates REST methods by adding hidden _method input with real method
@@ -212,24 +241,20 @@ class Joosy.Form extends Joosy.Module
   # 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']}
+  # @example Flat validation result
+  #   { field1: ['error'] }             # input
+  #   { field1: ['error'] }             # if form was not associated with Resource by {#fill}
+  #   { "fluffy[field1]": ['error']}    # if form was associated with Resource (named fluffy)
   #
-  # * Complex validation result
-  #   # input
-  #   { foo: { bar: { baz: ['error'] } } }
-  #   # output
-  #   { "foo[bar][bar]": ['error'] }
+  # @example Complex validation result
+  #   { foo: { bar: { baz: ['error'] } } }    # input
+  #   { "foo[bar][bar]": ['error'] }          # output
   #
   # @param [Object] errors        Data to prepare
   #
+  # @return [Hash<String, Array>]          Flat hash with field names in keys and arrays 
+  #   of errors in values
+  #
   __stringifyErrors: (errors) ->
     result = {}
     
@@ -257,16 +282,18 @@ class Joosy.Form extends Joosy.Module
   #
   # Flattens complex inline structures into form notation
   #
-  # Example:
+  # @example Basic flattening
   #   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
   #
+  # @return [Hash]
+  #
   __foldInlineEntities: (hash, scope="", result={}) ->
     Object.each hash, (key, value) =>
       if Object.isObject(value)

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

@@ -0,0 +1,30 @@
+#= require joosy/core/joosy
+
+#
+# Rendering and string representation helpers
+#
+Joosy.helpers 'Application', ->
+  
+  #
+  # Converts \n into <br/> in your text
+  #
+  # @param [String] text      Text to convert
+  #
+  @nl2br = (text) ->
+    text.toString().replace /\n/g, '<br/>'
+
+  #
+  # Wraps the inline block into given template
+  # Request template will receive the inline block as @yield parameter
+  # 
+  # Example
+  #   -# foo/baz template
+  #   != @renderWrapped 'foo/bar', ->
+  #     %b This string will be passed to 'foo/bar'
+  #
+  #   -# foo/bar template
+  #   %h1 I'm the wrapper here!
+  #     != @yield
+  #
+  @renderWrapped = (template, lambda) ->
+    @render template, Joosy.Module.merge(this, yield: lambda())

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

@@ -1,70 +1,129 @@
-@Joosy = Object.extended
-  debug: false
+#
+# All the tiny core stuff
+#
+# @module
+#
+@Joosy =
+  #
+  # Core modules container
+  #
   Modules: {}
+  
+  #
+  # Resources container
+  #
   Resource: {}
+  
+  #
+  # Templaters container
+  #
   Templaters: {}
 
-Joosy.namespace = (name, generator=false) ->
-  name  = name.split '.'
-  space = window
-  for part in name
-    space = space[part] ?= {}
-
-  if generator
-    generator = generator.apply space
-  for key, klass of space
-    if space.hasOwnProperty(key) &&
-       Joosy.Module.hasAncestor klass, Joosy.Module
-      klass.__namespace__ = name
-
-Joosy.helpers = (name, generator) ->
-  Joosy.namespace "Joosy.Helpers.#{name}", generator
-
-Joosy.test = ->
-  text = "Hi :). I'm Joosy. And everything is just fine!"
-
-  if console
-    console.log text
-  else
-    alert text
-
-Joosy.uuid = ->
-  'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace /[xy]/g, (c) ->
-    r = Math.random() * 16 | 0
-    v = if c is 'x' then r else r & 3 | 8
-    v.toString 16
-  .toUpperCase()
-
-Joosy.preloadImages = (images, callback) ->
-  unless Object.isArray(images)
-    images = [images]
-  if images.length == 0
-    callback()
-
-  ticks   = images.length
-  result  = []
-  checker = ->
-    if (ticks -= 1) == 0
-      callback?()
-
-  for p in images
-    result.push $('<img/>').load(checker).attr('src', p)
-
-  result
-
-Joosy.buildUrl = (url, params) ->
-  paramsString = []
-
-  Object.each params, (key, value) ->
-    paramsString.push "#{key}=#{value}"
-
-  hash = url.match(/(\#.*)?$/)[0]
-  url  = url.replace /\#.*$/, ''
-  if !paramsString.isEmpty() && !url.has(/\?/)
-    url  = url + "?"
-
-  paramsString = paramsString.join '&'
-  if !paramsString.isBlank() && url.last() != '?'
-    paramsString = '&' + paramsString
-
-  url + paramsString + hash
+  #
+  # If enabled Joosy will log to console a lot of 'in progress' stuff
+  #
+  debug: false
+
+  #
+  # Registeres anything inside specified namespace (objects chain starting from `window`)
+  #
+  # @example Basic usage
+  #   Joosy.namespace 'foobar', ->
+  #     class @RealThing
+  # 
+  #   foo = new foobar.RealThing
+  #
+  # @param [String] name            Namespace keyword
+  # @param [Boolean] generator      Namespace content
+  #
+  namespace: (name, generator=false) ->
+    name  = name.split '.'
+    space = window
+    for part in name
+      space = space[part] ?= {}
+
+    if generator
+      generator = generator.apply space
+    for key, klass of space
+      if space.hasOwnProperty(key) &&
+         Joosy.Module.hasAncestor klass, Joosy.Module
+        klass.__namespace__ = name
+
+  #
+  # Registeres given methods as a helpers inside a given set
+  #
+  # @param [String] name            Helpers set keyword
+  # @param [Boolean] generator      Helpers content
+  #
+  helpers: (name, generator) ->
+    Joosy.namespace "Joosy.Helpers.#{name}", generator
+
+  #
+  # Scary `hello world`
+  #
+  test: ->
+    text = "Hi :). I'm Joosy. And everything is just fine!"
+
+    if console
+      console.log text
+    else
+      alert text
+
+  #
+  # Generates UUID
+  #
+  uuid: ->
+    'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace /[xy]/g, (c) ->
+      r = Math.random() * 16 | 0
+      v = if c is 'x' then r else r & 3 | 8
+      v.toString 16
+    .toUpperCase()
+
+  #
+  # Preloads sets of images then runs callback
+  #
+  # @param [Array<String>] images             Images paths
+  # @param [Function] callback                Action to run when every picture was loaded (or triggered an error)
+  #
+  preloadImages: (images, callback) ->
+    unless Object.isArray(images)
+      images = [images]
+    if images.length == 0
+      callback()
+
+    ticks   = images.length
+    result  = []
+    checker = ->
+      if (ticks -= 1) == 0
+        callback?()
+
+    for p in images
+      result.push $('<img/>').load(checker).error(checker).attr('src', p)
+
+    result
+
+  #
+  # Basic URI builder. Joins base path with params hash
+  #
+  # @param [String] url         Base url
+  # @param [Hash] params        Parameters to join
+  #
+  # @example Basic usage
+  #   Joosy.buildUrl 'http://joosy.ws/#!/test', {foo: 'bar'}    # http://joosy.ws/?foo=bar#!/test
+  #
+  buildUrl: (url, params) ->
+    paramsString = []
+
+    Object.each params, (key, value) ->
+      paramsString.push "#{key}=#{value}"
+
+    hash = url.match(/(\#.*)?$/)[0]
+    url  = url.replace /\#.*$/, ''
+    if !paramsString.isEmpty() && !url.has(/\?/)
+      url  = url + "?"
+
+    paramsString = paramsString.join '&'
+    if !paramsString.isBlank() && url.last() != '?'
+      paramsString = '&' + paramsString
+
+    url + paramsString + hash