faalis 0.20.0 → 0.21.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5b6bebb09df183b7dee476937557f6891913cb06
-  data.tar.gz: 7641a768cd23e508dd287ab678301916716259f8
+  metadata.gz: e7d77be09881beddd4d13f35ae2ad54576a8ecaf
+  data.tar.gz: 95fac973732a6d0be6cd34a359e71b1d58592201
 SHA512:
-  metadata.gz: 25e2961ee63d2a0e48fa2419246207f3345dcc25a27bbc216b677752dc89400400e53f81e81316e6cf3c5cecabd1755ffad90355df42db71c3f5a6735915c4c8
-  data.tar.gz: 6e02192d12bc51edbe48c1dd46db63a9818c90d31698aa24a13c153148504f7f1bd91c701f1c82709cc378cac10409d24bec37a1aeffa05ab645e9484866fc27
+  metadata.gz: da3e1dbe6d99f4954ca6a7774bb97159b95ffc7feab3c849ce5526f62b1df1404ec0e9896b05670253a5f97cd0b5009b591d4fcc058d3ea5d524425321a2989c
+  data.tar.gz: f75f7d92eac57912f2c4a917ef6bbc67876097c04248c2814cd0e1d3015d1ddcc7261b673bb4f4e743ddb1211e602e96e27fda534a9be52c65e06f7f4a064105

data/app/controllers/faalis/api_controller.rb

@@ -19,19 +19,26 @@
 require_dependency "faalis/api_controller"
 
 
+# This class is the base class of all API controllers in any **Faalis**
+# host applications. Each host Rails application should have an `APIController`
+# which inherit from this class.
 class Faalis::APIController < Faalis::ApplicationController
+
+  @@allowed_fields = []
+
+  # Only support `json` format
   respond_to :json
 
-  before_filter :authenticate_user!
+  # Authenticate user before any action take place
+  before_filter :authenticate
 
   protect_from_forgery
 
+  # Set csrf cookie after any action
   after_filter :set_csrf_cookie_for_ng
 
-  def set_csrf_cookie_for_ng
-    cookies['XSRF-TOKEN'] = form_authenticity_token if protect_against_forgery?
-  end
-
+  # Rescue from any access denied exception raised from cancan and
+  # returns a useful error message in json
   rescue_from CanCan::AccessDenied do |exception|
 
     render :status => 403, :json => {
@@ -41,11 +48,91 @@ class Faalis::APIController < Faalis::ApplicationController
     }
   end
 
+  def set_csrf_cookie_for_ng
+    cookies['XSRF-TOKEN'] = form_authenticity_token if protect_against_forgery?
+  end
+
+  # User authentication for API services take place here. By default
+  # **Faalis** uses the authentication method of **Devise** to authenticate
+  # access to API service.
+  #
+  # If you want to change authentication method ? just override this method
+  # in you **APIController**
+  def authenticate
+    authenticate_user!
+  end
+
+  # Load resource by using parameters specified in querystring.
+  def load_resource_by_query
+    # If any query string parameter provided and allow fields specified
+    if not request.query_parameters.empty? and not allowed_fields.empty?
+      #load_resource
+
+      # Iterate over parameters in query string
+      request.query_parameters.each do |key, value|
+        # each key can be like filename[__querytype]=value
+        # which `querytype` is string that specify the query type scope
+        # to use in model. For example these is a query type scope called
+        # `gt` which mean the mentioned field should be greater than the
+        # value
+        field, query_type = key.split("__")
+
+        if allowed_fields.include? field
+          # If field name is in the allowed list
+          # If no query type specified we will use assignment scope.
+          if query_type.nil?
+            query_type = "assignment"
+          end
+
+          # If model have an scope with the "#{query_type}_query" name.
+          # Otherwise skip
+          if model_class.respond_to? "#{query_type}_query"
+
+            # If resource already loaded. If there was a instnace variable
+            # with the plural name of the resource exists then resource
+            # already loaded and we should chain new conditions
+            if instance_variable_defined? "@#{controller_name}"
+              instance_variable_get("@#{controller_name}").send("#{query_type}_query".to_sym, field, value)
+            else
+              # Resource did not loaded we make first query
+              # (without touching database) and set the corresponding
+              # instance variables
+              relation_object = model_class.send("#{query_type}_query".to_sym, field, value)
+              instance_variable_set("@#{controller_name}", relation_object)
+            end
+
+          else
+            logger.info "There is no `#{query_type}_query` in `#{model_class.to_s}` model."
+          end
+        else
+          logger.warn "`#{field}` in not in allowed list for `#{self.class.to_s}`."
+        end
+
+      end
+    end
+  end
+
+  # An array of allowed fields for query loading
+  def allowed_fields
+    @@allowed_fields
+  end
+
+  # Using this query you can activate the query loading system
+  # and specify fields which you want to use in query loading
+  def self.allow_query_on(*args)
+    @@allowed_fields = args.to_a.collect { |x| x.to_s }
+  end
+
+
   protected
 
+  # Model class related to this controller.
+  def model_class
+    controller_name.singularize.classify.constantize
+  end
+
   def verified_request?
     super || form_authenticity_token == request.headers['X-XSRF-TOKEN']
   end
 
-
 end

data/app/models/faalis/user.rb

@@ -52,7 +52,12 @@ module Faalis
     devise *@@devise_options
 
     def name
-      "#{first_name} #{last_name}"
+      if first_name or last_name
+        "#{first_name} #{last_name}"
+      else
+        email
+      end
+
     end
 
     def full_name

data/app/views/faalis/api/v1/users/index.json.jbuilder

@@ -1,4 +1,4 @@
 json.array! @users do |user|
-  json.extract! user, :id, :email, :first_name, :last_name
+  json.extract! user, :id, :email, :first_name, :last_name, :name
   json.group user.group, :id, :name
 end

data/lib/faalis/generators/concerns/angular.rb

@@ -1,6 +1,12 @@
 module Faalis
   module Generators
     module Concerns
+
+      # This **Concern** looks for `raw_path` and `path` in scaffold
+      # json file which both of them are optional.
+      # Using `raw_path` you can override the full path of generate file.
+      # and with `path` you can override the directory name inside
+      # `app/assets/javascripts`.
       module Angular
 
         def self.included(base)
@@ -13,7 +19,7 @@ module Faalis
 
         private
 
-
+        # return the relative path to place where scaffold shoud be created.
         def angularjs_app_path
           if not resource_data["raw_path"].blank?
             resource_data["raw_path"]

data/lib/faalis/generators/concerns/dependency.rb

@@ -1,6 +1,20 @@
 module Faalis
   module Generators
     module Concerns
+
+      # This **Concern** adds support of dependencies to scaffold using
+      # `deps` key in json file. You can provide a list of scaffold dependencies
+      # which should mention as dependecy of **Angularjs** module of scaffold.
+      # Example:
+      #
+      #```javascript
+      #   ....
+      #   "deps": [
+      #       "module1",
+      #       "module2"
+      #   ],
+      #   ...
+      #```
       module Dependency
 
         def self.included(base)
@@ -8,6 +22,7 @@ module Faalis
           #base.class_option :deps, :type => :string, :default => "", :desc => "Dependencies of Angularjs module, comma separated"
         end
 
+        # Return a list of dependencies.
         def deps
           resource_data[:deps]
         end

data/lib/faalis/generators/concerns/json_input.rb

@@ -6,9 +6,8 @@ module Faalis
     module Concerns
       # This module Provide an argument for generator which
       # is needed by other `Concerns`.
-      #
-      # Each Concern will have its own
-
+      # Each Concern will have its own entry in scaffold json
+      # file. For documentation on each entry checkout its concern class
       module JsonInput
 
         def self.included(base)
@@ -18,11 +17,14 @@ module Faalis
 
         private
 
+        # Read the json file and returns its raw data
         def json_file_data
           path = File.expand_path(jsonfile)
           File.read(path)
         end
 
+        # Return the hash related to json structure from cache or by
+        # reading file.
         def resource_data
           if @data
             @data

data/lib/faalis/generators/concerns/menu.rb

@@ -1,6 +1,18 @@
 module Faalis
   module Generators
     module Concerns
+      # This **concern** adds support of side menu to scaffold and `menu` key
+      # to jsonfile. `menu` key is an array which each element represent a menu
+      # entry and should be and object with following keys:
+      #
+      # `title`: Title of submenu
+      #
+      # `url`: Url of submenu link
+      #
+      # `action`: Permissions related action to check on resource model.
+      #
+      # `model`: Model of related resource which permission action should be check
+      #          against.
       module Menu
 
         def self.included(base)

data/lib/faalis/generators/concerns/model.rb

@@ -1,6 +1,9 @@
 module Faalis
   module Generators
     module Concerns
+      # This **concern** adds support for `model` key inside jsonfile which
+      # allow you to override the name of resource default model name.
+      # Resource model name is used in some processes like permission system.
       module Model
 
         def self.included(base)
@@ -11,10 +14,12 @@ module Faalis
 
         private
 
+        # Does an alternative `model` is specified ?
         def model_specified?
           resource_data.include? "model"
         end
 
+        # Name of alternative `model`
         def model
           if model_specified?
             resource_data["model"]

data/lib/faalis/generators/concerns/parent.rb

@@ -1,6 +1,32 @@
 module Faalis
   module Generators
     module Concerns
+
+      # This **concern** adds the methods needed to support nested resource
+      # in any dashboad generators. This module adds `parents` key to jsonfile
+      # which is an array of resource parents in right order.
+      # For example if we have a nested resource like:
+      #
+      # ```ruby
+      # resources :blogs do
+      #   resources :categories do
+      #     resources :posts
+      #   end
+      # end
+      # ```
+      #
+      # And we want to create an dashboard scaffold for `post` resource we have
+      # to add `parent` key to our json file like this:
+      #
+      # ```json
+      # ...
+      # "parents": [
+      #     "blog",
+      #     "category"
+      # ]
+      # ...
+      # ```
+      # Please pay attention to singular form of name of parents in json defination
       module Parent
 
         def self.included(base)
@@ -12,8 +38,10 @@ module Faalis
 
         # check for parent
         def parent?
-          unless resource_data["parents"].empty?
-            return true
+          unless resource_data. include? "parents"
+            unless resource_data["parents"].nil?
+              return true
+            end
           end
           false
         end
@@ -23,6 +51,7 @@ module Faalis
           path.gsub(/^\//, "")
         end
 
+        # Return an array of resource parents
         def parents
           if parent?
             _parents = resource_data["parents"]

data/lib/faalis/generators/concerns/required.rb

@@ -1,6 +1,9 @@
 module Faalis
   module Generators
     module Concerns
+
+      # Adds `required` key to `fields`. Fields with this key as true will
+      # be non optional fields
       module RequireFields
 
         def self.included(base)

data/lib/faalis/generators/concerns/resource_fields.rb

@@ -4,6 +4,32 @@ require "faalis/generators/fields/relation"
 module Faalis
   module Generators
     module Concerns
+      # This **concern** module is one of the most important **concerns** in
+      # dashboard scaffold system. This module adds `fields` key to json file
+      # which use for defining the resource fields. `fields` key is an array
+      # of objects which each object represent a field. Each field have following
+      # attributes:
+      #
+      # **name**: Name of field
+      #
+      # **type**: Type of field. some of the most important types are: `string`,
+      #         `integer`, `flout`, `belongs_to`, `has_many`, `in`, `datetime`.
+      #          For complete list of types take a look at
+      #          `app/assets/javascripts/faalis/dashboard/modules/fields/`
+      #
+      # **to**: This attribute is just for `in`, `has_many` and `belongs_to` field
+      #       types which define the resource that current resource have dependency
+      #       with. Bear in mind that `in` type uses `to` attrbute as an array of
+      #       possible value for field and will render as a combobox.
+      #
+      # **options**: An object of type related objects. For example a list of
+      #            current resource parents just like `parent` key.
+      #
+      # **bulk**: All fields with true as `bulk` value will be used in bulk editor.
+      #
+      # **tab**: ID of a Tab that this field should be appear on.
+      #
+      # **required**: Field will be non optional.
       module ResourceFields
 
         def self.included(base)
@@ -19,6 +45,7 @@ module Faalis
         # [name, type]
         def fields
           fields = []
+          if have_fields?
           resource_data["fields"].each do |field|
             name = field["name"]
             type = field["type"]
@@ -30,6 +57,7 @@ module Faalis
             end
 
             fields << [name, type]
+            end
           end
           fields
         end
@@ -99,6 +127,15 @@ module Faalis
         def no_filter?
           resource_data.include? "no_filter" &&  resource_data["no_filter"]
         end
+
+        def have_fields?
+          unless resource_data.include? "fields"
+            unless resource_data["fields"].nil?
+              return true
+            end
+          end
+          false
+        end
       end
     end
   end

data/lib/faalis/generators/concerns/resource_name.rb

@@ -1,6 +1,7 @@
 module Faalis
   module Generators
     module Concerns
+      # Adds the `name` key to json file which specify the resource name.
       module ResourceName
 
         def self.included(base)

data/lib/faalis/generators/concerns/tabs.rb

@@ -1,6 +1,11 @@
 module Faalis
   module Generators
     module Concerns
+      # Using this **concern** module user can specify an array of tab objects
+      # which each one has an `id` and `name` attribute. Tabs will be added to
+      # **new** view of resource. Also this concern will a `tab` key to field
+      # object. All the fields with same `id` as a tab will be grouped in that
+      # tab
       module Tabs
 
         def self.included(base)

data/lib/faalis/version.rb

@@ -18,5 +18,5 @@
 # -----------------------------------------------------------------------------
 
 module Faalis
-  VERSION = "0.20.0"
+  VERSION = "0.21.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: faalis
 version: !ruby/object:Gem::Version
-  version: 0.20.0
+  version: 0.21.0
 platform: ruby
 authors:
 - Sameer Rahmani
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-03-16 00:00:00.000000000 Z
+date: 2014-03-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails