drg_cms 0.4.39 → 0.4.53

data/app/controllers/dc_application_controller.rb

@@ -21,31 +21,47 @@
 # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #++
+
+##########################################################################
+# Controller holds methods which are of use for all application controllers.
+##########################################################################
 class DcApplicationController < ActionController::Base
   protect_from_forgery
   
 ########################################################################
-# Writes anything passed as parameter to log/dump file.
+# Writes anything passed as parameter to logger file.
 # 
 # Very usefull for debuging strange errors.
 ########################################################################
 def dc_dump(*args)
   args.each do |arg|
-    File.open(Rails.root.join('log/dump.log'),'a') {|f| f.write(arg.to_s + "\n") }
+    logger.debug arg.to_s
   end
 end
   
 ####################################################################
-# return true if in edit mode
+# Return true if CMS is in edit mode
 ####################################################################
 def dc_edit_mode?
   session[:edit_mode] > 1
 end
 
 ####################################################################
-# Return true if user has required role
+# Checks if user has required role.
+# 
+# [Parameters:]
+# [role] 
+# Role can be passed as DcPolicyRole object or as string. If string
+# is passed, dc_policy_roles files is searched for appropriate role.
+# 
+# [Return:]
+# Boolean. True if user has required role added to his profile.
+# 
+# [Example:]
+#    if dc_user_has_role('admin') ...
+#    if dc_user_has_role('Site editors') ...
 ####################################################################
-def dc_user_has_role( role, user=session[:user_id] )
+def dc_user_has_role(role)
   if role.class == String
     rol = role
     role = DcPolicyRole.find_by(name: rol)
@@ -57,7 +73,12 @@ def dc_user_has_role( role, user=session[:user_id] )
 end
 
 ####################################################################
-# Determine site from url and return site record (document)
+# Determine site from url and return site document. 
+# 
+# [Return:]
+# Site document. If site is not found and not in production environment 'test' 
+# site document is returned. If site has alias set then alias site document is
+# returned.
 ####################################################################
 def dc_get_site()
   return @site if @site 
@@ -80,24 +101,33 @@ end
 ####################################################################
 # Determine and return site record from url. It would be nice but it is not working.
 ####################################################################
-def self.dc_get_site_()
+def self.dc_get_site_() #:nodoc:
   #self.dc_get_site()
 end
 
 ########################################################################
-# Searches forms file in forms path and returns it's name.
+# Searches forms path for file_name and returns full file name or nil if not found.
+# 
+# [Parameters:]
+# [form_file] Additional data can be displayed with error.
+# 
+# [Return:]
+# String. Full form file name or nil if not found.
 ########################################################################
-def dc_find_form_file(form)
+def dc_find_form_file(form_file)
   DrgCms.paths(:forms).reverse.each do |path|
-    f = "#{path}/#{form}.yml"
+    f = "#{path}/#{form_file}.yml"
     return f if File.exist?(f)
   end
-  p "Form file #{form} not found!"
+  p "Form file #{form_file} not found!"
   nil
 end
 
 #######################################################################
-# Render 404 error with some debug includded
+# Will render public/404.html file with some debug code includded.
+# 
+# [Parameters:]
+# [Object where_the_error_is] Additional data can be displayed with error.
 ########################################################################
 def dc_render_404(where_the_error_is=nil)
   render(file: "#{Rails.root}/public/404", :status => 404, :layout => false, :formats => [:html], 
@@ -105,7 +135,8 @@ def dc_render_404(where_the_error_is=nil)
 end
 
 ########################################################################
-# Log visit to dc_visit 
+# Will write document to dc_visits collection unless visit comes from robot. 
+# It also sets session[is_robot] variable to true if robot.
 ########################################################################
 def dc_log_visit()
   if request.env["HTTP_USER_AGENT"] and request.env["HTTP_USER_AGENT"].match(/\(.*https?:\/\/.*\)/)
@@ -126,31 +157,34 @@ protected
 #############################################################################
 # Add permissions. Subroutine of dc_user_can
 ############################################################################
-def add_permissions_l(table_name=nil) # NODOC
+def add_permissions_for(table_name=nil) # :nodoc:
   perm = table_name.nil? ? DcPermission.find_by(is_default: true) : DcPermission.find_by(table_name: table_name, active: true)
   (perm.dc_policy_rules.each {|p1| @permissions[p1.dc_policy_role_id] = p1.permission }) if perm
 end
 
 ############################################################################
-# Returns true if user's role permits to perform operation on a table(collection) 
-# with required permission.
+# Checks if user can perform (read, create, edit, delete) document in specified
+# table (collection).
+# 
+# [Parameters:]
+# [Integer permission] Required permission level
+# [String table] Name of table(collection) for which permission is required. Defaults to params[table].
 # 
-# @example 
-#   dc_user_can(DcPermission::CAN_VIEW, params[:table])
+# [Returns:]
+# Boolean true if user's role permits operation on a table(collection) with required permission.
 # 
-# @param [ permission ] Required permission level
-# @param [ table ] Name of table(collection) for which permission is required
-#   Defaults to params[:table]
+# [Example:]
+#     dc_user_can(DcPermission::CAN_VIEW, params[:table])
 ############################################################################
 def dc_user_can(permission, table=params[:table])
   if @permissions.nil?
     @permissions = {}
-    add_permissions_l # default permission
+    add_permissions_for # default permission
     table_name = ''
 # permission can be set for table or object embedded in table. Read all possible values  
     table.strip.downcase.split(';').each do |t|
       table_name << (table_name.size > 0 ? ';' : '') + t # table;embedded;another;...
-      add_permissions_l table_name
+      add_permissions_for table_name
     end
   end
 # Sometimes anonymous user is allowed to use cmsedit. Search for system default role.
@@ -165,8 +199,7 @@ def dc_user_can(permission, table=params[:table])
 end  
 
 ####################################################################
-# Detects if called from mobile agent.
-# According to http://detectmobilebrowsers.com/
+# Detects if called from mobile agent according to http://detectmobilebrowsers.com/
 ####################################################################
 def dc_set_is_mobile
   is_mobile = /(android|bb\d+|meego).+mobile|avantgo|bada\/|blackberry|blazer|compal|elaine|fennec|hiptop|iemobile|ip(hone|od)|iris|kindle|lge |maemo|midp|mmp|netfront|opera m(ob|in)i|palm( os)?|phone|p(ixi|re)\/|plucker|pocket|psp|series(4|6)0|symbian|treo|up\.(browser|link)|vodafone|wap|windows (ce|phone)|xda|xiino/i.match(request.user_agent) || /1207|6310|6590|3gso|4thp|50[1-6]i|770s|802s|a wa|abac|ac(er|oo|s\-)|ai(ko|rn)|al(av|ca|co)|amoi|an(ex|ny|yw)|aptu|ar(ch|go)|as(te|us)|attw|au(di|\-m|r |s )|avan|be(ck|ll|nq)|bi(lb|rd)|bl(ac|az)|br(e|v)w|bumb|bw\-(n|u)|c55\/|capi|ccwa|cdm\-|cell|chtm|cldc|cmd\-|co(mp|nd)|craw|da(it|ll|ng)|dbte|dc\-s|devi|dica|dmob|do(c|p)o|ds(12|\-d)|el(49|ai)|em(l2|ul)|er(ic|k0)|esl8|ez([4-7]0|os|wa|ze)|fetc|fly(\-|_)|g1 u|g560|gene|gf\-5|g\-mo|go(\.w|od)|gr(ad|un)|haie|hcit|hd\-(m|p|t)|hei\-|hi(pt|ta)|hp( i|ip)|hs\-c|ht(c(\-| |_|a|g|p|s|t)|tp)|hu(aw|tc)|i\-(20|go|ma)|i230|iac( |\-|\/)|ibro|idea|ig01|ikom|im1k|inno|ipaq|iris|ja(t|v)a|jbro|jemu|jigs|kddi|keji|kgt( |\/)|klon|kpt |kwc\-|kyo(c|k)|le(no|xi)|lg( g|\/(k|l|u)|50|54|\-[a-w])|libw|lynx|m1\-w|m3ga|m50\/|ma(te|ui|xo)|mc(01|21|ca)|m\-cr|me(rc|ri)|mi(o8|oa|ts)|mmef|mo(01|02|bi|de|do|t(\-| |o|v)|zz)|mt(50|p1|v )|mwbp|mywa|n10[0-2]|n20[2-3]|n30(0|2)|n50(0|2|5)|n7(0(0|1)|10)|ne((c|m)\-|on|tf|wf|wg|wt)|nok(6|i)|nzph|o2im|op(ti|wv)|oran|owg1|p800|pan(a|d|t)|pdxg|pg(13|\-([1-8]|c))|phil|pire|pl(ay|uc)|pn\-2|po(ck|rt|se)|prox|psio|pt\-g|qa\-a|qc(07|12|21|32|60|\-[2-7]|i\-)|qtek|r380|r600|raks|rim9|ro(ve|zo)|s55\/|sa(ge|ma|mm|ms|ny|va)|sc(01|h\-|oo|p\-)|sdk\/|se(c(\-|0|1)|47|mc|nd|ri)|sgh\-|shar|sie(\-|m)|sk\-0|sl(45|id)|sm(al|ar|b3|it|t5)|so(ft|ny)|sp(01|h\-|v\-|v )|sy(01|mb)|t2(18|50)|t6(00|10|18)|ta(gt|lk)|tcl\-|tdg\-|tel(i|m)|tim\-|t\-mo|to(pl|sh)|ts(70|m\-|m3|m5)|tx\-9|up(\.b|g1|si)|utst|v400|v750|veri|vi(rg|te)|vk(40|5[0-3]|\-v)|vm40|voda|vulc|vx(52|53|60|61|70|80|81|83|85|98)|w3c(\-| )|webc|whit|wi(g |nc|nw)|wmlb|wonu|x700|yas\-|your|zeto|zte\-/i.match(request.user_agent[0..3])
@@ -175,7 +208,9 @@ end
 
 
 ##########################################################################
-# Merge values from params fields (from site, page ...) into internal @options hash.
+# Merge values from parameters fields (from site, page ...) into internal @options hash.
+# [Parameters:]
+# [String parameters] String in yaml syntax.
 ##########################################################################
 def dc_set_options(parameters)
   @options ||= {}
@@ -195,9 +230,21 @@ def dc_set_options(parameters)
 end
 
 ##########################################################################
-# Default request processing.
+# This is default page process action. It will search for site, page and
+# design documents, collect parameters from different objects, add CMS edit code if allowed
+# and at the end render design.body or design.rails_view or site.rails_view.
+# 
+# [Example:] as defined in routes.rb
+#    get '*path' => 'dc_application_controller#dc_process_default_request'
+#    # or
+#    get '*path' => 'my_controller#page'
+#    # then in my_controller.rb
+#    def page
+#      dc_process_default_request
+#    end
+#    
 ##########################################################################
-def dc_process_default_request()
+def dc_process_default_request() 
   session[:edit_mode] ||= 0
 # Initialize parts
   @parts    = nil
@@ -213,11 +260,11 @@ def dc_process_default_request()
   pageclass = @site.page_table.classify.constantize
   if params[:id]
     #Page.where(id: params[:id]).or(subject_link: params[:id]).first    
-    @page = pageclass.find_by(:dc_site_id.in => [@site._id, nil], subject_link: params[:id])
+    @page = pageclass.find_by(:dc_site_id.in => [@site._id, nil], subject_link: params[:id], active: true)
     @page = pageclass.find(params[:id]) if @page.nil? # I think that there will be more subject_link searchers than id
   elsif params[:path]
 # path may point direct to page's subject_link
-    @page = pageclass.find_by(:dc_site_id.in => [@site._id, nil], subject_link: params[:path])
+    @page = pageclass.find_by(:dc_site_id.in => [@site._id, nil], subject_link: params[:path], active: true)
     if @page.nil?
 # no. Find if defined in links
       link = DcLink.find_by(:dc_site_id.in => [@site._id, nil], name: params[:path])
@@ -263,13 +310,17 @@ def dc_process_default_request()
 end
 
 ########################################################################
-# Decamelizes string. It probably doesn't work very good with non ascii chars.
-# Therefore it is very unwise to use non ascii chars for table (collection) names.
+# Decamelizes string. Does oposite from camelize method. It probably doesn't work 
+# very good with non ascii chars. Since this method is used for converting from model
+# to collection names it is very unwise to use non ascii chars for table (collection) names.
+# 
+# [Parameters:]
+# [String string] String to be converted # 'DcSimpleMenu' => 'dc_simple_menu'.
 ########################################################################
-def decamelize_type(st)
-  return nil unless st
+def decamelize_type(string)
+  return nil unless string
   r = ''
-  st.to_s.each_char do |c|
+  string.to_s.each_char do |c|
     r << case 
       when r.size == 0     then c.downcase
       when c.downcase != c then '_' + c.downcase
@@ -282,7 +333,11 @@ end
 ####################################################################
 # Return's error messages for the document formated for display on edit form.
 # 
-# @param [ document ] Document var
+# [Parameters:]
+# [document] Document which will be examined for errors.
+# 
+# [Return:]
+# String. HTML code for displaying error on edit form.
 ####################################################################
 def dc_error_messages_for(document)
   return '' unless document.errors.any?
@@ -304,10 +359,23 @@ end
 ####################################################################
 # Checks if any errors exist on document and writes debug log. It can also 
 # crash if requested. This is mostly usefull in development for debuging 
-# model errors.
+# model errors or when saving to multiple collections and where each save must be 
+# checked if succesfull.
 # 
-# @param [ document ] Document var
-# @param [ crash ] Should crash when errors detected. Default = false.
+# [Parameters:]
+# [Object document] Document var
+# [Boolean crash] Should crash when errors detected. Default = false.
+# 
+# [Return:]
+# String. Documents error message empty string if everything is OK.
+# 
+# [Example:]
+#    model.save
+#    if (msg = dc_check_model(model) ).size > 0
+#      p msg
+#      error process ......
+#    end
+#      
 ####################################################################
 def dc_check_model(document, crash=false)
   return nil unless document.errors.any?
@@ -315,18 +383,20 @@ def dc_check_model(document, crash=false)
   document.errors.each do |attribute, errors_array|
     msg << "#{attribute}: #{errors_array}\n"
   end
-  logger.debug(msg)
+  logger.debug(msg) if msg.size > 0
   crash_it if crash
   msg
 end
 
 ######################################################################
-# Can call rake task from controller.
-# @example 
-#   dc_call_rake('clear:all', some_parm: some_id)
+# Call rake task from controller.
+# 
+# [Parameters:]
+# [String task] Rake task name
+# [Hash options] Options that will be send to task as environment variables
 # 
-# @param [ task ] Rake task name
-# @param [ options ] Options that will be send to task as environment variables
+# [Example:]
+#    dc_call_rake('clear:all', some_parm: some_id)
 ######################################################################
 def dc_call_rake(task, options = {})
   options[:rails_env] ||= Rails.env
@@ -335,12 +405,22 @@ def dc_call_rake(task, options = {})
 end
 
 ######################################################################
-# Small helper for formating ajax return from controller. This is higly experimental.
-# @example 
-#   dc_render_ajax(operation: :div, prepand: html_code)
+# Small helper for rendering ajax return code from controller. When ajax call is
+# made from DRG CMS form return may be quite complicated. All ajax return combinations 
+# can be found in drg_cms.js file. 
+# 
+# [Parameters:]
+# [Hash opts] Different options
+# 
+# [Return:]
+# String. Formatted to be used on ajax return.
+# 
+# [Example:]
+#    html_code = '<span>Some text</span>'
+#    dc_render_ajax(div: 'mydiv', prepand: html_code) # Will prepand code to mydiv div
+#    dc_render_ajax(class: 'myclass', append: html_code) # Will append code to all objects with myclass class
+#    dc_render_ajax(operation: 'window', value: "/pdf_file.pdf") # will open pdf file in new window.
 # 
-# @param [ task ] Rake task name
-# @param [ options ] Options that will be send to task as environment variables
 ######################################################################
 def dc_render_ajax(opts)
   result = {}
@@ -360,13 +440,19 @@ def dc_render_ajax(opts)
 end
 
 ########################################################################
-# Find document by parameters 
-# @example 
-#   dc_find_document(params[:table], params[:id], params[:ids]
+# Find document by parameters. This is how cmsedit finds document based
+# on url parameters.
+# 
+# [Parameters:]
+# [String table] Table (collection) name. Could be dc_page;dc_part;... when searching for embedded document.
+# [String id] Id of the document
+# [String table] Ids of parent documents when document is embedded. Ids are separated by ; char. 
+# 
+# [Return:]
+# Document. Required document or nil if not found.
 # 
-# @param [ table ] table (collection) name. Could be dc_page;dc_part;... when embedded document
-# @param [ id ] Id of the document
-# @param [ ids ] Ids of parent documents when document is embedded. Ids are separated by ; char. 
+# [Example:] 
+#    dc_find_document(params[:table], params[:id], params[:ids])
 ########################################################################
 def dc_find_document(table, id, ids)
   tables = table.split(';')

data/app/controllers/dc_common_controller.rb

@@ -22,11 +22,27 @@
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #++
 
+########################################################################
+# This controller holds some common actions used by CMS.
+########################################################################
 class DcCommonController < DcApplicationController
 layout false
 
 ########################################################################
-# Autocomplete request, for search fiels
+# This action is called on ajax autocomplete call. It checks if user has rights to
+# wiev data. 
+# 
+# Url parameters:
+# [table] Table (collection) model name in lower case indicating table which will be searched.
+# [id] Name of id key field that will be returend. Default is '_id'
+# [input] Search data entered in input field.
+# [search] when passed without dot it defines field name on which search 
+# will be performed. When passed with dot class_method.method_name is assumed. Method name will
+# be parsed and any class with class method name can be avalueted. Class method must accept
+# input parameter and return array [ [_id, value],.. ] which will be used in autocomplete field.
+# 
+# Return:
+# JSON array [label, value, id] of first 20 documents that confirm to query.
 ########################################################################
 def autocomplete
 #  return '' unless session[:edit_mode] > 0 # 
@@ -34,7 +50,7 @@ def autocomplete
 # TODO Double check if previous line works as it should.
   table = params['table'].classify.constantize
   id = [params['id']] || '_id'
-# call method in class if search parameter has . This is for user defined sofisticated searches
+# call method in class if search parameter has . This is for user defined searches
 # result must be returned as array of [id, search_field_value]
   a = if params['search'].match(/\./)
     name, method = params['search'].split('.')
@@ -51,13 +67,13 @@ def autocomplete
 end
 
 ########################################################################
-# Register and save click on ad link
+# Register and record click when ad link is clicked.
 ########################################################################
 def ad_click
   if (ad = DcAd.find(params[:id]))
     ad.clicked += 1
     ad.save
-    DcAdStat.create!(dc_ad_id: params[:id], ip: request.ip, type: 2 ) #.save
+    DcAdStat.create!(dc_ad_id: params[:id], ip: request.ip, type: 2 ) 
   else
     logger.error "ERROR ADS: Invalid ad id=#{params[:id]} ip=#{request.ip}."
   end
@@ -66,13 +82,14 @@ def ad_click
 end
 
 ##########################################################################
-# Toggle cmd edit mode
+# Toggle CMS edit mode.This action is called when user clicks CMS option on 
+# top of the browser.
 ##########################################################################
 def toggle_edit_mode
   session[:edit_mode] ||= 0 
 # called directly without authorization  
   if session[:edit_mode] < 1 
-    dc_render_404 #(:file => "#{Rails.root}/public/404", :status => 404, :layout => false, :formats => [:html])
+    dc_render_404 
   else
     session[:edit_mode] = (session[:edit_mode] == 1) ? 2 : 1
     redirect_to params[:return_to]
@@ -80,15 +97,17 @@ def toggle_edit_mode
 end
 
 ####################################################################
-# Process login action
+# Default user login action.
 ####################################################################
 def process_login
 # Something is really wrong
   return dc_render_404 unless ( params[:record] and params[:record][:username] and params[:record][:password] )
-
-  user  = DcUser.find_by(username: params[:record][:username])
-  if user and user.authenticate(params[:record][:password])
-    fill_login_data(user, params[:record][:remember_me].to_i == 1)  
+  
+  if params[:record][:password].to_s.size > 0  #password must not be empty
+    user  = DcUser.find_by(username: params[:record][:username])
+    if user and user.authenticate(params[:record][:password])
+      fill_login_data(user, params[:record][:remember_me].to_i == 1)
+    end
   else
     flash[:error]      = t('drgcms.invalid_username')
     params[:return_to] = params[:return_to_error] # return_to error
@@ -97,7 +116,7 @@ def process_login
 end
 
 ####################################################################
-# Process logout action
+# Default user logout action.
 ####################################################################
 def logout
   clear_login_data
@@ -105,7 +124,8 @@ def logout
 end
 
 ####################################################################
-# Alternative login. If remember_me cookie is found it tries to automatically logs
+# Alternative login action with remember_me cookie. If found it will automatically 
+# login user otherwise user will be presented with regular login dialog.
 ####################################################################
 def login
   if cookies.signed[:remember_me]
@@ -126,7 +146,7 @@ def login
 end
 
 ####################################################################
-# Processes restore from journal action
+# Action is called when restore document from journal is requested.
 ####################################################################
 def restore_from_journal
 # selected fields to hash  
@@ -161,24 +181,6 @@ def restore_from_journal
   render inline: result.to_json, formats: 'js'  
 end
 
-########################################################################
-# Update some anomalies in json 
-########################################################################
-def update_json(json, is_update=false)
-  result = {}
-  json.each do |k,v|
-    if v.class == Hash
-      result[k] = v['$oid'] if is_update
-    elsif v.class == Array
-      result[k] = []
-      v.each {|e| result[k] << update_json(e, is_update)}
-    else
-      result[k] = v
-    end
-  end 
-  result
-end
-
 ########################################################################
 # Copy current record to clipboard as json text. It will actually ouput an 
 # window with data formatted as json.
@@ -202,6 +204,8 @@ end
 
 ########################################################################
 # Paste data from clipboard into text_area and update documents in destination database.
+# This action is called twice. First time for displaying text_area field and second time 
+# ajax call for processing data.
 ########################################################################
 def paste_clipboard
 # Only administrators can perform this operation  
@@ -236,6 +240,24 @@ end
 
 protected
 
+########################################################################
+# Update some anomalies in json data on paste_clipboard action.
+########################################################################
+def update_json(json, is_update=false) #:nodoc:
+  result = {}
+  json.each do |k,v|
+    if v.class == Hash
+      result[k] = v['$oid'] if is_update
+    elsif v.class == Array
+      result[k] = []
+      v.each {|e| result[k] << update_json(e, is_update)}
+    else
+      result[k] = v
+    end
+  end 
+  result
+end
+
 ########################################################################
 # Processes one document. Subroutine of paste_clipboard.
 ########################################################################
@@ -262,7 +284,7 @@ def process_document(line, table, id, ids)
 end
 
 ####################################################################
-# Clears all session data related to login
+# Clears all session data related to login. 
 ####################################################################
 def clear_login_data
   session[:edit_mode]   = 0
@@ -273,7 +295,7 @@ def clear_login_data
 end
 
 ####################################################################
-# Fills session with data related to succesfull login.
+# Fills session with data related to successful login.
 ####################################################################
 def fill_login_data(user, remember_me)
   session[:user_id]   = user.id