joosy 0.1.0.alpha → 1.0.0.RC1

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

@@ -0,0 +1,338 @@
+#= require joosy/core/joosy
+#= require joosy/core/modules/module
+#= require joosy/core/modules/log
+#= 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 highlights. It can
+# read common server error responses and add .field_with_errors class to proper 
+# field.
+#
+# 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 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
+#
+# @include Joosy.Modules.Log
+# @include Joosy.Modules.Events
+# @include Joosy.Modules.Container
+#
+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'
+
+  #
+  # Makes one AJAX request with form data without binding
+  #
+  # @see #constructor
+  #
+  # @param [Element] form          Instance of HTML form element
+  # @param [Hash] options          Options
+  #
+  @submit: (form, options={}) ->
+    form = new @(form, options)
+    form.container.submit()
+    form.unbind()
+    null
+
+  @attach: ->
+    new Joosy.Form arguments...
+
+  #
+  # During initialization replaces your basic form submit with AJAX request
+  #
+  # @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.
+  #
+  # @note For browsers having no support of HTML5 Forms it may do an iframe requests
+  # to handle file uploading.
+  #
+  # @param [jQuery] form        Form element instance
+  # @param [Hash] options       Options
+  #
+  # @option options [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.
+  #
+  # @option options [Function] success       `(Object) -> null` triggers on 200 HTTP code from server. 
+  #   Pases in the parsed JSON.
+  #
+  # @option options [Function] progress      `(Float) -> null` runs periodically while form is uploading
+  #
+  # @option options [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.
+  #
+  # @option options [Joosy.Resource.Generic] resource      The resource to fill the form with
+  # @option options [String] resourceName                  The string to use as a resource name prefix for fields to match invalidation
+  # @option options [String] action                        Action URL for the form
+  #
+  constructor: (form, options={}) ->
+    if Object.isFunction options
+      @success = options
+    else
+      Object.each options, (key, value) =>
+        @[key] = value
+
+    @container = $(form)
+    return if @container.length == 0
+
+    @refreshElements()
+    @__delegateEvents()
+
+    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...
+      xhr: =>
+        xhr = $.ajaxSettings.xhr()
+        if xhr.upload? && @progress
+          xhr.upload.onprogress = (event) =>
+            if event.lengthComputable
+              @progress (event.position / event.total * 100).round 2
+        xhr
+
+    if options.resource?
+      @fill(options.resource, options)
+      delete @resource
+
+  #
+  # Resets form submit behavior to default
+  #
+  unbind: ->
+    @container.unbind('submit').find('input:submit,input:image,button:submit').unbind('click');
+
+  #
+  # 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 [Hash] options           Options
+  #
+  # @option options [Function] decorator     `(Object) -> Object` decoration callback
+  #   Pases in the parsed JSON.
+  #
+  # @option options [String] action          Action URL for the form
+  #
+  fill: (resource, options) ->
+    resource = resource.build() if Object.isFunction(resource.build)
+    @__resource = resource
+
+    if options?.decorator?
+      data = options.decorator resource.data
+    else
+      data = resource.data
+
+    Object.each data, (key, 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'
+
+    @__markMethod(options?.method || 'PUT') if resource.id()
+
+    url = options?.action || (if resource.id()? then resource.memberPath() else resource.collectionPath())
+
+    @container.attr 'action', url
+    @container.attr 'method', 'POST'
+
+  #
+  # 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
+      @success? response
+    else if response.status == 200
+      @success response.json
+    else
+      @__error response.json
+
+  #
+  # 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.
+  #
+  __error: (data) ->
+    errors = if data.responseText
+      try
+        data = jQuery.parseJSON(data.responseText)
+      catch error
+        {}
+    else
+      data
+
+    if !@error? || @error(errors) is true
+      errors = @__stringifyErrors(errors)
+      
+      Object.each errors, (field, notifications) =>
+        input = @findField(field).addClass @invalidationClass
+        @notification? input, notifications
+
+      return errors
+
+    return false
+  
+  #
+  # 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
+  # while setting POST as the transport method
+  #
+  # @param [String] method      Real method to simulate
+  #
+  __markMethod: (method='PUT') ->
+    method = $('<input/>',
+      type: 'hidden'
+      name: '_method'
+      value: 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
+  #
+  # @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)
+  #
+  # @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 = {}
+    
+    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()
+          if @__resource
+            name    = @resourceName || @__resource.__entityName
+            field   = name + "[#{field}]"
+          field  += "[#{f}]" for f in splited
+      
+        else if @__resource
+          name  = @resourceName || @__resource.__entityName
+          field = name + "[#{field}]"
+
+        result[field] = notifications
+
+    result
+
+  #
+  # Flattens complex inline structures into form notation
+  #
+  # @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)
+        @__foldInlineEntities(value, "#{scope}[#{key}]", result)
+      else
+        result["#{scope}[#{key}]"] = value
+
+    result

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

@@ -0,0 +1,72 @@
+#= require joosy/core/joosy
+
+#
+# Form helper
+#
+Joosy.helpers 'Application', ->
+
+  description = (resource, method, extendIds) ->
+    if resource instanceof Joosy.Resource.Generic
+      id        = resource.id()
+      resource  = resource.__entityName
+
+    name: resource + "#{if method.match(/^\[.*\]$/) then method else "[#{method}]"}"
+    id:   resource + (if id && extendIds then '_'+id else '') + "_#{method.parameterize().underscore()}"
+
+  input = (type, resource, method, options={}) =>
+    d = description(resource, method, options.extendIds)
+    delete options.extendIds
+    @tag 'input', Joosy.Module.merge {type: type, name: d.name, id: d.id}, options
+
+  class Form
+    constructor: (@context, @resource, @options) ->
+    label: (method, options={}, content='') -> @context.label(@resource, method, Joosy.Module.merge(extendIds: @options.extendIds, options), content)
+    radioButton: (method, tagValue, options={}) -> @context.radioButton(@resource, method, tagValue, Joosy.Module.merge(extendIds: @options.extendIds, options))
+    textArea: (method, options={}) -> @context.textArea(@resource, method, Joosy.Module.merge(extendIds: @options.extendIds, options))
+    checkBox: (method, options={}, checkedValue=1, uncheckedValue=0) ->
+      @context.checkBox(@resource, method, Joosy.Module.merge(extendIds: @options.extendIds, options), checkedValue, uncheckedValue)
+
+  ['text', 'file', 'hidden', 'password'].each (type) =>
+    Form.prototype[type+'Field'] = (method, options={}) ->
+      @context[type+'Field'] @resource, method, Joosy.Module.merge(extendIds: @options.extendIds, options)
+
+  @formFor = (resource, options={}, block) ->
+    if Object.isFunction(options)
+      block   = options
+      options = {}
+
+    uuid = Joosy.uuid()
+    form = @tag 'form', Joosy.Module.merge(options.html || {}, id: uuid), block?.call(this, new Form(this, resource, options))
+
+    @onRefresh? -> Joosy.Form.attach '#'+uuid, Joosy.Module.merge(options, resource: resource)
+
+    form
+
+  @label = (resource, method, options={}, content='') ->
+    if !Object.isObject(options)
+      content = options
+      options = {}
+
+    d = description(resource, method, options.extendIds)
+    delete options.extendIds
+
+    @tag 'label', Joosy.Module.merge(options, for: d.id), content
+
+  ['text', 'file', 'hidden', 'password'].each (type) =>
+    @[type+'Field'] = (resource, method, options={}) -> input type, resource, method, options
+
+  @radioButton = (resource, method, tagValue, options={}) -> input 'radio', resource, method, Joosy.Module.merge(value: tagValue, options)
+
+  @checkBox = (resource, method, options={}, checkedValue=1, uncheckedValue=0) ->
+    spy = input 'hidden', resource, method, value: uncheckedValue, extendIds: options.extendIds
+    box = input 'checkbox', resource, method, Joosy.Module.merge(value: checkedValue, options)
+
+    spy+box
+
+  @textArea = (resource, method, options={}) ->
+    value     = options.value
+    extendIds = options.extendIds
+    delete options.value
+    delete options.extendIds
+
+    @tag 'textarea', Joosy.Module.merge(description(resource, method, extendIds), options), value

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

@@ -0,0 +1,42 @@
+#= require joosy/core/joosy
+
+#
+# Rendering and string representation helpers
+#
+Joosy.helpers 'Application', ->
+  
+  @tag = (name, options={}, content='') ->
+    content = content() if Object.isFunction(content)
+
+    element = document.createElement name
+    temp    = document.createElement 'div'
+
+    Object.each options, (name, value) -> element.setAttribute name, value
+    element.innerHTML = content
+
+    temp.appendChild element
+    temp.innerHTML
+
+  #
+  # 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/helpers/widgets.js.coffee

@@ -0,0 +1,14 @@
+#= require joosy/core/joosy
+
+#
+# Widgets manipulation
+#
+Joosy.helpers 'Application', ->
+
+  @widget = (element, widget) ->
+    uuid    = Joosy.uuid()
+    element = @tag element, id: uuid
+
+    @onRefresh -> @registerWidget '#'+uuid, widget
+
+    element

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

@@ -0,0 +1,184 @@
+#
+# All the tiny core stuff
+#
+# @mixin
+#
+@Joosy =
+  #
+  # Core modules container
+  #
+  Modules: {}
+  
+  #
+  # Resources container
+  #
+  Resource: {}
+  
+  #
+  # Templaters container
+  #
+  Templaters: {}
+
+  #
+  # 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
+
+  #
+  # Runs set of callbacks finializing with result callback
+  #
+  # @example Basic usage
+  #   Joosy.synchronize (context) ->
+  #     contet.do (done) -> done()
+  #     contet.do (done) -> done()
+  #     content.after ->
+  #       console.log 'Success!'
+  #
+  # @param [Function] block           Configuration block (see example)
+  #
+  synchronize: ->
+    Joosy.Modules.Events.synchronize arguments...
+
+  #
+  # 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
+
+  #
+  # Creates classes and collection classes for the given resources that might have been extracted from the routes
+  #
+  # @param [Hash] resources      Resources declaration
+  #
+  # @example Basic usage
+  #   Joosy.defineResources {'': {foo: '/foos'}, 'namespace': {bar: '/namespace/bars'}}
+  #
+  defineResources: (resources) ->
+    Object.extended(resources).each (namespace, resources) ->
+      if namespace.isBlank()
+        Object.extended(resources).each (resource, path) ->
+          Joosy.defineResource resource, path
+      else
+        Joosy.namespace namespace, ->
+          Object.extended(resources).each (resource, path) =>
+            Joosy.defineResource resource, path, @
+
+  #
+  #
+  # @param [String] resource      Entity name in singular form
+  # @param [String] path          Entity REST end-point
+  # @param [Object] space         Namespace for new classes
+  #
+  # @example Basic usage
+  #   Joosy.defineResource 'foo', '/foos'
+  #
+  defineResource: (resource, path, space=window) ->
+    className = resource.camelize()
+    collectionName = "#{resource.pluralize().camelize()}Collection"
+    unless space[className]
+      Joosy.Modules.Log.debugAs space, "Define #{className}"
+      space[className] = class extends Joosy.Resource.REST
+        @entity resource
+        @source path
+    unless space[collectionName]
+      Joosy.Modules.Log.debugAs space, "Define #{collectionName}"
+      space[collectionName] = class extends Joosy.Resource.RESTCollection
+        @model space[className]