drg_cms 0.4.39 → 0.4.53

data/app/helpers/dc_ad_renderer.rb

@@ -22,7 +22,18 @@
 #++
 
 ########################################################################
-#
+# Ads renderer. Typically ads renderer is defined in design like this.
+#    <div id="ads-on-top">
+#       <%= dc_render(:dc_ad, position: 'top') %>
+#    </div>
+# 
+# There can be more than one ad shown on the same position. Therefore Ads can be grouped by position 
+# they are displayed at. Position name can be any string. I suggest using top, right ... 
+# 
+# Ads may be prioritized. Higher priority means higher probability that ad will be selected for display. 
+# 
+# Clicks on picture and flash can be intercepted and are saved into dc_ad_stat table. 
+# It is also possible to limit number of times ad will be displayed or clicked. 
 ########################################################################
 class DcAdRenderer
   
@@ -31,7 +42,7 @@ include DcApplicationHelper
 ########################################################################
 #
 ########################################################################
-def initialize( parent, opts={} )
+def initialize( parent, opts={} ) #:nodoc:
   @parent = parent
   @opts   = opts
   @css    = ''
@@ -39,9 +50,9 @@ def initialize( parent, opts={} )
 end
 
 ########################################################################
-#
+# Finds ads that will be rendered. Subroutine of multi method.
 ########################################################################
-def find_ads_multi()
+def find_ads_multi() #:nodoc:
   ads = DcAd.where( position: @opts[:position], active: true).to_a#, :valid_to.gt => Time.now, :valid_from.lt => Time.now).to_a
 #p @opts, ads.size, '*-*-*-*'
   ads.delete_if { |ad| (ad.valid_to and ad.valid_to < Time.now) or 
@@ -53,7 +64,8 @@ def find_ads_multi()
 end
 
 ########################################################################
-# Default method for rendering ads
+# This is an experiment of how to render multiple ads on same location simultaneously by
+# fade in and out div on which ad resides.
 ########################################################################
 def multi
   return '' if @parent.session[:is_robot] # don't bother if robot
@@ -103,7 +115,7 @@ EOJS
 end
 
 ########################################################################
-#
+# Determines which add will be displayed next. Subroutine of default method.
 ########################################################################
 def find_ad_to_display()
   ads = DcAd.where( dc_site_id: @parent.site._id, position: @opts[:position], active: true).to_a#, :valid_to.gt => Time.now, :valid_from.lt => Time.now).to_a
@@ -126,9 +138,9 @@ def find_ad_to_display()
 end
 
 ########################################################################
-# Create flash link for ad
+# Code for flash ad.
 ########################################################################
-def flash_link(ad)
+def flash_ad(ad)
   click_tag = ad.link.to_s.size > 5 ? "flashvars=\"clickTag=#{ad.link}\"" : '' 
 <<EOT
 <div class="link_to_track" id="#{ad.id}">
@@ -149,14 +161,14 @@ EOT
 end
 
 ########################################################################
-# Create picture link for ad
+# Code for picture ad.
 ########################################################################
-def picture_link(ad)
+def picture_ad(ad)
   @parent.link_to @parent.image_tag(ad.file), ad.link, id: ad.id, class: 'link_to_track', target: ad.link_target 
 end
 
 ########################################################################
-# Default method for rendering ads
+# Default method for rendering ads. 
 ########################################################################
 def default
   return '' if @parent.session[:is_robot] # don't bother if robot
@@ -171,9 +183,9 @@ def default
     end
     html << case ad.type
     when 1 then # picture
-      picture_link ad
+      picture_ad ad
     when 2 then # flash
-      flash_link ad
+      flash_ad ad
     when 3 then # script
       ad.script
     else
@@ -184,7 +196,7 @@ def default
 end
 
 ########################################################################
-# Render HTML
+# Renderer dispatcher. Method returns HTML part of code.
 ########################################################################
 def render_html
   method = @opts[:method] || 'default'
@@ -197,7 +209,7 @@ def render_html
 end
 
 ########################################################################
-# Render CSS
+# Render CSS. This method returns css part of code.
 ########################################################################
 def render_css
   @css

data/app/helpers/dc_application_helper.rb

@@ -22,42 +22,75 @@
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #++
 
+
+###########################################################################
+# 
+# DcApplicationHelper defines common helper methods for using with DRG CMS.
+#
+###########################################################################
 module DcApplicationHelper
-attr_reader :page, :design, :site, :tables, :ids, :form, :options
+# page document
+attr_reader :page
+# design document
+attr_reader :design
+# site document
+attr_reader :site
+# tables url parameter
+attr_reader :tables
+# ids url parameter
+attr_reader :ids
+# form object
+attr_reader :form
+# options object
+attr_reader :options
+
+# all parts read from page, design, ...
 attr_accessor :parts
 
 ############################################################################
-# Calls part renderer to return part of design.
+# This is main method used for render parts of design into final HTML document.
+# 
+# Parameters:
+# [renderer] String or Symbol. Class name (in lowercase) that will be used to render final HTML code. 
+# If class name is provided without '_renderer' suffix it will be added automatically.
+# [opts] Hash. Additional options that are passed to method. Options are merged with
+# options set on site, design, page and passed to renderer object.
+# 
+# Example:
+#    <%= dc_render(:dc_page, method: 'view', category: 'news') %>
 ############################################################################
 def dc_render(renderer, opts={})
-  type = renderer.to_s.downcase
   opts[:edit_mode]  = session[:edit_mode] 
-# TODO Check why did I always put return_to into link and will this break something  
-#  opts[:editparams] = { return_to: request.url }
   opts[:editparams] = {}
   opts = @options.merge(opts) # merge options with parameters passed on site, page, design ...
-  opts.symbolize_keys!           # this makes lots of things easier
+  opts.symbolize_keys!        # this makes lots of things easier
 # Create renderer object
-  klass = (type + '_renderer').classify
-  obj = Kernel.const_get(klass, Class.new).new(self, opts)
+  klass = renderer.to_s.downcase
+  klass += '_renderer' unless klass.match('_renderer') #
+  obj = Kernel.const_get(klass.classify, Class.new).new(self, opts) rescue nil
 # 
-  html = obj.render_html
-  @css  << obj.render_css.to_s
-  html.nil? ? '' : html.html_safe # nil can happened  
+  if obj
+    html = obj.render_html
+    @css  << obj.render_css.to_s
+    html.nil? ? '' : html.html_safe # nil can happened  
+  else
+    "Class #{klass} not defined!"
+  end
 end
 
 ########################################################################
-# Used for designs with lots of common code and one part which is different.
+# Used for designs with lots of common code and one (or more) part which differs.
+# It will simply replace anchor code with value of variable.
 # 
 # Example: As used in design. Backslashing < and % is important \<\%
-# <% part = "<div  class='some-class'>\<\%= dc_render(:my_renderer, method: 'render_method') \%\></div>" %>
-# <%= dc_replace_in_design(piece: 'piece_name', replace: '[main]', with: part) %>
+#    <% part = "<div  class='some-class'>\<\%= dc_render(:my_renderer, method: 'render_method') \%\></div>" %>
+#    <%= dc_replace_in_design(piece: 'piece_name', replace: '[main]', with: part) %>
 # 
 # Want to replace more than one part. Use array.
-# <%= dc_replace_in_design(replace: ['[part1]','[part2]'], with: [part1, part2]) %>
+#    <%= dc_replace_in_design(replace: ['[part1]','[part2]'], with: [part1, part2]) %>
 # 
-# This helper is replacement for 'script' method defined in dc_piece_renderer, 
-# but it can also use design defined in site document if piece parameter is not set.
+# This helper is replacement for old 'script' method defined in dc_piece_renderer, 
+# but it uses design defined in site document if piece parameter is not set.
 ########################################################################
 def dc_replace_in_design(opts={})
   design = opts[:piece] ? DcPiece.find(name: opts[:piece]).script : dc_get_site.design
@@ -73,26 +106,38 @@ def dc_replace_in_design(opts={})
 end
 
 ########################################################################
+# Old method name. 
 ########################################################################
-def dc_render_design(opts={}) #NODOC
+def dc_render_design(opts={}) #:nodoc:
   p "dc_render_design will be deprecated. Use dc_replace_in_design instead."  
   dc_replace_in_design(opts)
 end
 
 ############################################################################
-# Creates title for dialog. Title also has pagination link on its right side.
+# Creates title div for DRG CMS dialogs. Title may also contain pagination section on right side if 
+# result_set is provided as parameter.
+# 
+# Parameters:
+# [text] String. Title caption.
+# [result_set=nil] Document collection. If result_set is passed pagination links will be created.
+#  
+# Returns:
+# String. HTML code for title.
 ############################################################################
-def dc_table_title(text, result=nil)
+def dc_table_title(text, result_set=nil)
   c = "<table width='100%' cellspacing='0' cellpadding='1' class='dc-title'><tr><td>#{text}</td>"
-  if result and result.respond_to?(:current_page)
-    c << "<td align='right' style='font-size: 0.8em;'> #{paginate(result, :params => {:action => 'index'})}</td>" 
+  if result_set and result_set.respond_to?(:current_page)
+    c << "<td align='right' style='font-size: 0.8em;'> #{paginate(result_set, :params => {:action => 'index'})}</td>" 
   end
   c << '<tr></table>'
   c.html_safe
 end
 
 ############################################################################
-# Creates title for cmsedit edit dialog. 
+# Creates title for cmsedit edit action dialog. 
+#  
+# Returns:
+# String. HTML code for title.
 ############################################################################
 def dc_edit_title()
   c = "#{t('drgcms.edit')} : "
@@ -103,7 +148,10 @@ def dc_edit_title()
 end
 
 ############################################################################
-# Creates title for cmsedit new dialog. 
+# Creates title for cmsedit new action dialog. 
+# 
+# Returns:
+# String. HTML code for title.
 ############################################################################
 def dc_new_title()
   if @form['table'] == 'dc_dummy'
@@ -114,7 +162,11 @@ def dc_new_title()
 end
 
 ####################################################################
-# Creates label for edit dialog.
+# Formats label and html input code for display on edit form.
+#  
+#  Parameters:
+#  [input_html] String. HTML code for data input field.
+#  [label] String. Input field label.
 ####################################################################
 def dc_label_for(input_html, label)
   c =<<eot
@@ -127,7 +179,10 @@ eot
 end
 
 ####################################################################
-# Returns messages saved in flash formated for display. 
+# Returns flash messages formatted for display on message div.
+# 
+# Returns:
+# String. HTML code formatted for display.
 ####################################################################
 def dc_flash_messages()
   err  = @parent ? @parent.flash[:error]   : flash[:error]
@@ -158,11 +213,17 @@ end
 ########################################################################
 # Decamelizes string. This probably doesn't work very good with non ascii chars.
 # Therefore it is very unwise to use non ascii chars for table (collection) names.
+# 
+# Parameters: 
+# [string] String. String to be converted into decamelized string.
+# 
+# Returns:
+# String. Decamelized string.
 ########################################################################
-def decamelize_type(st)
-  return nil if st.nil?
+def decamelize_type(string)
+  return nil if string.nil?
   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
@@ -173,19 +234,26 @@ def decamelize_type(st)
 end
 
 ####################################################################
-# return error messages for the record
+# Returns validation error messages for the document (record) formatted for 
+# display on message div.
+# 
+# Parameters: 
+# [doc] Document. Document record which will be checked for errors.
+# 
+# Returns:
+# String. HTML code formatted for display.
 ####################################################################
-def dc_error_messages_for(r)
-  return '' unless r.errors.any?
+def dc_error_messages_for(doc)
+  return '' unless doc.errors.any?
   msgs = ''
-  r.errors.each do |attribute, errors_array|
-    label = t("helpers.label.#{decamelize_type(r.class)}.#{attribute}", attribute)
+  doc.errors.each do |attribute, errors_array|
+    label = t("helpers.label.#{decamelize_type(doc.class)}.#{attribute}", attribute)
     msgs << "<li>#{label} : #{errors_array}</li>"
   end
   
 c = <<eot
 <div class="dc-form-error"> 
-  <h2>#{t('drgcms.errors_no')} #{r.errors.size}</h2>  
+  <h2>#{t('drgcms.errors_no')} #{doc.errors.size}</h2>  
   <ul>#{msgs}</ul>  
 </div>
 eot
@@ -193,14 +261,30 @@ eot
 end
 
 ####################################################################
-# return true if in edit mode
+# Checks if CMS is in edit mode (CMS menu bar is visible).
+#  
+# Returns:
+# Boolean. True if in edit mode
 ####################################################################
 def dc_edit_mode?
   (@parent ? @parent.session[:edit_mode] : session[:edit_mode]) > 1
 end
 
 ####################################################################
-# Return create link for drg_cms
+# Will create HTML code required to create new document.
+# 
+# Parameters: 
+# [opts] Hash. Optional parameters for url_for helper. These options must provide at least table and formname
+# parameters. 
+# 
+# Example:
+#    if @opts[:edit_mode] > 1
+#      opts = {table: 'dc_page;dc_part', formname: 'dc_part', ids: @doc.id }
+#      html << dc_link_for_create( opts.merge!({title: 'Add new part', 'dc_part.name' => 'initial name', 'dc_part.order' => 10}) ) 
+#    end
+# 
+# Returns:
+# String. HTML code which includes add image and javascript to invoke new document create action.
 ####################################################################
 def dc_link_for_create(opts)
   title  = opts.delete(:title) #
@@ -217,7 +301,17 @@ def dc_link_for_create(opts)
 end
 
 ####################################################################
+# Will create HTML code required to edit document.
 # 
+# Parameters: 
+# [opts] Hash. Optional parameters for url_for helper. These options must provide at least table and formname
+# and id parameters. 
+# 
+# Example:
+#    html << dc_link_for_edit( @options ) if @opts[:edit_mode] > 1
+#    
+# Returns:
+# String. HTML code which includes edit image and javascript to invoke edit document action.
 ####################################################################
 def dc_link_for_edit(opts)
   title = opts.delete(:title) #
@@ -235,9 +329,9 @@ def dc_link_for_edit(opts)
 end
 
 ####################################################################
-# Create edit link for drg_cms
+# Create edit link with edit picture. Subroutine of dc_page_edit_menu.
 ####################################################################
-def dc_link_menu_tag(title)
+def dc_link_menu_tag(title) #:nodoc:
   html =<<EOT
   <dl>
   <dt><div class='drgcms_popmenu' href="#"><span><img style="cursor:pointer;" src="/assets/drg_cms/edit.png" title="#{title}"></span></div></dt>
@@ -249,18 +343,33 @@ EOT
 end
 
 ####################################################################
-# Create one option in page edit link
+# Create one option in page edit link. Subroutine of dc_page_edit_menu.
 ####################################################################
-def dc_link_for_edit1(opts, link_text) #NODOC
+def dc_link_for_edit1(opts, link_text) #:nodoc:
   url = @parent.url_for(opts)
   "<li><div class='drgcms_popmenu_item' style='cursor: pointer;' data-url='#{url}'>#{link_text}</div></li>\n"
 end
 
 ########################################################################
-# Create edit menu for dc_page document.
+# Create edit menu for editing existing or creating new dc_page documents. Edit menu
+# consists of for options.
+# * Edit content. Will edit only body part od document.
+# * Edit advanced. Will create edit form for editing all document fields.
+# * New page. Will create new document and pass some initial data to it. Initial data is saved to cookie.
+# * New part. Will create new part of document.
+# 
+# Parameters:
+# [opts] Hash. Optional parameters for url_for helper. These options must provide at least table and formname
+# and id parameters. 
+# 
+# Example:
+#    html << dc_page_edit_menu() if @opts[:edit_mode] > 1
+# 
+# Returns: 
+# String. HTML code required for manipulation of currently processed document.
 ########################################################################
-def dc_page_edit_menu()
-  return '' if @opts[:edit_mode] < 2
+def dc_page_edit_menu(opts=@opts)
+  return '' if opts[:edit_mode] < 2
 # save some data to cookie. This can not go to session.
   t = @parent.site.page_table
   kukis = { "#{t}.dc_design_id" => @page.dc_design_id,
@@ -272,82 +381,110 @@ def dc_page_edit_menu()
   @parent.cookies[:record] = Marshal.dump(kukis)
   title = "#{t('drgcms.edit')}: #{@page.subject}"
   dc_link_menu_tag(title) do |html|
-    @opts[:editparams].merge!( :controller => 'cmsedit', :action => 'edit' )
-    @opts[:editparams].merge!( :id => @page.id, :table => @parent.site.page_table, formname: nil, edit_only: 'body' )
-    html << dc_link_for_edit1( @opts[:editparams], t('drgcms.edit_content') )
+    opts[:editparams].merge!( :controller => 'cmsedit', :action => 'edit' )
+    opts[:editparams].merge!( :id => @page.id, :table => @parent.site.page_table, formname: nil, edit_only: 'body' )
+    html << dc_link_for_edit1( opts[:editparams], t('drgcms.edit_content') )
     
-    @opts[:editparams][:edit_only] = nil
-    html << dc_link_for_edit1( @opts[:editparams], t('drgcms.edit_advanced') )
+    opts[:editparams][:edit_only] = nil
+    html << dc_link_for_edit1( opts[:editparams], t('drgcms.edit_advanced') )
     
-    @opts[:editparams][:action] = 'new'
-    html << dc_link_for_edit1( @opts[:editparams], t('drgcms.edit_new_page') )
+    opts[:editparams][:action] = 'new'
+    html << dc_link_for_edit1( opts[:editparams], t('drgcms.edit_new_page') )
 
-    @opts[:editparams].merge!(ids: @page.id, formname: 'dc_part', table: "#{@parent.site.page_table};dc_part"  )
-    html << dc_link_for_edit1( @opts[:editparams], t('drgcms.edit_new_part') )
+    opts[:editparams].merge!(ids: @page.id, formname: 'dc_part', table: "#{@parent.site.page_table};dc_part"  )
+    html << dc_link_for_edit1( opts[:editparams], t('drgcms.edit_new_part') )
   end
 end
 
 ########################################################################
-# Return page class (from site record) which defines page_class table (collection)
-# used for saving page data. 
+# Return page class model defined in site document page_class field. 
 # 
-# Mostly used by forms, when some method must be called from page model.
+# Used in forms, when method must be called from page model and model is overwritten by 
+# user's own model.
 # 
-# @example usage from form description:
+# Example as used on form:
 #    30:
 #      name: link
 #      type: text_with_select
-#      eval: 'DcPageClass.all_pages_for_site(@parent.dc_get_site)'
+#      eval: 'dc_page_class.all_pages_for_site(@parent.dc_get_site)'
 ########################################################################
 def dc_page_class()
- dc_get_site.page_class.classify.constantize  
+  dc_get_site.page_class.classify.constantize  
 end
 
 ####################################################################
-# Wrapper for i18 t method, with some spice added
+# Wrapper for i18 t method, with some spice added. If translation is not found English
+# translation value will be returned. And if still not found default value will be returned if passed.
+# 
+# Parameters:
+# [key] String. String to be translated into locale.
+# [default] String. Value returned if translation is not found.
+# 
+# Example:
+#    t('translate.this','Enter text for ....')
+# 
+# Returns: 
+# String. Translated text. 
 ####################################################################
 def t(key, default='')
   c = I18n.t(key)
   if c.class == Hash or c.match( 'translation missing' )
     c = I18n.t(key, locale: 'en') 
 # Still not found. Return default if set
-    c = default unless default.blank?
+    c = default if c.match( 'translation missing' ) and !default.blank?
   end
   c
 end
 
 ####################################################################
-# Returns translated tablename. 
+# Returns table (collection) name translation for usage in dialog title. Tablename 
+# title is provided by helpers.label.table_name.tabletitle locale.
+# 
+# Parameters:
+# [tablename] String. Table (collection) name to be translated.
+# [default] String. Value returned if translation is not found.
+# 
+# Returns: 
+# String. Translated text. 
 ####################################################################
 def t_tablename(tablename, default=nil)
   t('helpers.label.' + tablename + '.tabletitle', default || tablename)
 end
 
 ############################################################################
-# Translation for field name label.
+# Returns label for field translated to current locale for usage on data entry form.
+# Translation is provided by lang.helpers.label.table_name.field_name locale. If
+# translation is not found method will capitalize field_name and replace '_' with ' '.
 ############################################################################
-def t_name(name, default='')
-  c = t("helpers.label.#{@form['table']}.#{name}", default)
-  c = name.capitalize.gsub('_',' ') if c.match( 'translation missing' )
+def t_name(field_name, default='')
+  c = t("helpers.label.#{@form['table']}.#{field_name}", default)
+  c = field_name.capitalize.gsub('_',' ') if c.match( 'translation missing' )
   c
 end
 
 ############################################################################
-# Return name (description) for specified field in document
+# When select field is used on form options for select can be provided by 
+# helpers.label.table_name.choices4_name locale. This is how select
+# field options are translated. Method returns selected choice translated
+# to current locale. 
 # 
-# @example usage from program
-#   dc_name4_value('dc_user', 'name', text.id)
-#
-# @example usage from form description
-#  columns:
-#    2: 
-#      name: site_id
-#      eval: dc_name4_value('site','name',@record['site_id'])
-#
-# @param [ model ] table (collection) model name.
-# @param [ field ] field name to return
-# @param [ id ] id to search for
+# Parameters:
+# [model] String. Table (collection) model name (lowercase).
+# [field] String. Field name used.
+# [value] String. Value of field which translation will be returned.
 # 
+# Example:
+#    # usage in program. Choice values for state are 'Deactivated:0,Active:1,Waiting:2'
+#    dc_name4_value('dc_user', 'state', @record.active )
+#
+#    # usage in form
+#    columns:
+#      2: 
+#        name: state
+#        eval: dc_name4_value dc_user, state
+#        
+# Returns: 
+# String. Descriptive text (translated) for selected choice value.
 ############################################################################
 def dc_name4_value(model, field, value)
   return '' if value.nil?
@@ -358,21 +495,26 @@ def dc_name4_value(model, field, value)
 end
 
 ############################################################################
-# Return name (description) for specified table and id
+# Will return descriptive text for id key when field in one table (collection) has belongs_to 
+# relation to other table.
 # 
-# @example usage from program
-#   dc_name4_id('dc_user', 'name', text.id)
-#
-# @example usage from form description
-#  columns:
-#    2: 
-#      name: site_id
-#      eval: name4_id('site','name',@record['site_id'])
+# Parameters:
+# [model] String. Table (collection) model name (lowercase).
+# [field] String. Field name holding the value of descriptive text.
+# [id] BSON Key. Key value.
+# 
+# Example:
+#    # usage in program.
+#    dc_name4_id('dc_user', 'name', dc_page.created_by)
 #
-# @param [ model ] table (collection) model name.
-# @param [ field ] field name to return
-# @param [ id ] id to search for
+#    # usage in form
+#    columns:
+#      2: 
+#        name: site_id
+#        eval: dc_name4_id,site,name
 # 
+# Returns: 
+# String. Name (descriptive value) for specified key in table.
 ############################################################################
 def dc_name4_id(model, field, id)
   return '' if id.nil?
@@ -382,37 +524,55 @@ def dc_name4_id(model, field, id)
 end
 
 ############################################################################
-# Return icon representation for boolean value. Icon is a picture of checked or unchecked box.
+# Return html code for icon presenting boolean value. Icon is a picture of checked or unchecked box.
 # 
-# @example usage from program
-#   dc_icon4_boolean(some_value)
-#
-# @example usage from form description
-#  columns:
-#    10: 
-#      name: active
-#      eval: dc_icon4_boolean
+# Parameters:
+# [value] Boolean.  
+# 
+# Example:
+#    # usage from program
+#    dc_icon4_boolean(some_value)
 #
-# @param [ value ] value 
+#    # usage from form description
+#    columns:
+#      10: 
+#        name: active
+#        eval: dc_icon4_boolean
 ############################################################################
-def dc_icon4_boolean(val)
-  dc_dont?(val) ? image_tag('drg_cms/checkbox-unchecked.png') : image_tag('drg_cms/checkbox-checked.png')
+def dc_icon4_boolean(value)
+  dc_dont?(value) ? image_tag('drg_cms/checkbox-unchecked.png') : image_tag('drg_cms/checkbox-checked.png')
 end
 
 ############################################################################
-# Safely output date/time value in desired format. Will return '' if value is nil.
+# Returns html code for displaying date/time formatted by strftime. Will return '' if value is nil.
 # 
-# Mostly used for calling from views.
+# Parameters:
+# [value] Date/DateTime/Time.  
+# [format] String. strftime format mask. Defaults to locale's default format.
 ############################################################################
-def dc_date_time(val, default=nil)
-  return '' if val.nil?
-  default = ( val.class == Date ? t('date.formats.default') : t('time.formats.default') ) if default.nil?
-  val.strftime(default)
+def dc_format_date_time(value, format=nil)
+  return '' if value.nil?
+  format ||= value.class == Date ? t('date.formats.default') : t('time.formats.default')
+  value.strftime(format)
 end
 
 ####################################################################
-# Determine and return site record from url. Site record will be cached in
+#
+####################################################################
+def dc_date_time(value, format) #:nodoc:
+  p 'dc_date_time will be deprecated! Use dc_format_date_time instead.'
+  dc_format_date_time(value, format)
+end
+
+####################################################################
+# Parse site name from url and return dc_site document. Site document will be cached in
 # @site variable.
+# 
+# If not in production environment and site document is not found
+# method will search for 'test' document and return dc_site document found in alias_for field.
+# 
+# Returns:
+# DCSite. Site document.
 ####################################################################
 def dc_get_site()
   return @site if @site # already cached
@@ -425,7 +585,7 @@ def dc_get_site()
     @site = DcSite.find_by(name: @site.alias_for)
   end
 # Development environment. Check if site with name test exists and use 
-# homepagelink field as pointer to real site name.
+# alias_for field as pointer to real site name.
   if @site.nil? and ENV["RAILS_ENV"] != 'production'
     @site = DcSite.find_by(name: 'test')
     @site = DcSite.find_by(name: @site.alias_for) if @site
@@ -436,9 +596,10 @@ end
 
 ############################################################################
 # Return array of policies defined in a site document formated to be used
-# as choices select field, where policy_id field is defined in document. 
+# as choices for select field. Method is used for selecting site policy where
+# policy for displaying data is required.
 # 
-# @example (as used in forms) 
+# Example (as used in forms):
 #    name: policy_id
 #    type: select
 #    eval: dc_choices4_site_policies
@@ -451,51 +612,77 @@ def dc_choices4_site_policies()
 end
 
 ############################################################################
-# Returns list of table names (collections) as array of choices for use in select field 
-# on data permission form. Method gets list of available collections from 
-# cms_menu.yml menu definition file.
+# Returns list of all collections (tables) as array of choices for usage in select fields.
+# List is collected from cms_menu.yml files and may not include all collections used in application.
+# Currently list is only used for helping defining collection names on dc_permission form. 
 # 
-# @example (as used in forms) 
-#   eval: dc_choices4_tables_list
-############################################################################
-def dc_choices4_tables_list
-  menus = []
+# Example (as used in forms):
+#    form:
+#      fields:
+#        10:
+#          name: table_name
+#          type: text_with_select
+#          eval: dc_choices4_all_collections      
+############################################################################
+def dc_choices4_all_collections
+  choices = {}
   DrgCms.paths(:forms).reverse.each do |path|
-    f = "#{path}/cms_menu.yml"
-    menus << YAML.load_file(f)['menu'] if File.exist?(f)
+    filename = "#{path}/cms_menu.yml"
+    next unless File.exist?(filename)
+#
+    menu = YAML.load_file(filename) rescue nil      # load menu
+    next if menu.nil? or !menu['menu']              # not menu or error
+    menu['menu'].each do |section|
+      next unless section.last['items']             # next if no items
+      section.last['items'].each do |k, v|          # look for caption and 
+        key = v['params']['table']
+        choices[key] ||= "#{t(v['caption'], v['caption'])} - #{key}" 
+      end
+    end
   end  
-#  
-  choices = [] #['Default permission','Default permission']]
-  menus.each do |section|  
-    section['items'].each do |e| 
-      c = t(e['caption'], e['caption'])
-      choices << ["#{c} - #{e['params']['table']}", e['params']['table']]
+  choices.invert.to_a.sort # hash has to be inverted for values to be returned right
+end
+
+########################################################################
+# Merges two forms when current form extends other form. Subroutine of dc_choices4_cmsmenu.
+# With a little help of https://www.ruby-forum.com/topic/142809 
+########################################################################
+def forms_merge(hash1, hash2) #:nodoc:
+  target = hash1.dup
+  hash2.keys.each do |key|
+    if hash2[key].is_a? Hash and hash1[key].is_a? Hash
+      target[key] = forms_merge(hash1[key], hash2[key])
+      next
     end
+    target[key] = hash2[key] == '/' ? nil :  hash2[key]
   end
-  choices
+# delete keys with nil value  
+  target.delete_if{ |k,v| v.nil? }
 end
 
 ##########################################################################
-# Returns available choices used by collection edit select field on CMS top menu.
-# 
-# @example: dc_choices4_cmsmenu
-# 
-# Returns 2d array ready for use in select field.
+# Returns choices for creating collection edit select field on CMS top menu.
 ##########################################################################
 def dc_choices4_cmsmenu()
-  menus = []
+  menus = {}
   DrgCms.paths(:forms).reverse.each do |path|
-    f = "#{path}/cms_menu.yml"
-    menus << YAML.load_file(f)['menu'] if File.exist?(f)
-  end  
+    filename = "#{path}/cms_menu.yml"
+    next unless File.exist?(filename)
+    menu = YAML.load_file(filename) rescue nil      # load menu
+    next if menu.nil? or !menu['menu']              # not menu or error
+    menus = forms_merge(menu['menu'], menus)        # ignore top level part
+ end
 #
   choices = []
-  menus.each do |v|
-    choices << ["--- #{ t(v['section'], v['section']) }",'#']
-    v['items'].each do |i| 
-      opts = { controller: i['controller'], action: i['action'] }
-      i['params'].each {|k,v| opts.merge!(k => v) }
-      choices << [ t(i['caption'],i['caption']), url_for( opts ) ] 
+  menus.to_a.sort.each do |one_menu|    # sort menus, result is array of sorted hashes
+    menu = one_menu[1]                  # value is the second (1) element of array
+    next unless menu['caption']
+    choices << ["--- #{ t(menu['caption'], menu['caption']) }",'#']
+    menu['items'].to_a.sort.each do |item|          # as above. sort items first 
+      key, value = item[0], item[1]
+      opts = { controller: value['controller'], action: value['action'] }
+      value['params'].each {|k,v| opts.merge!(k => v) }   # add parameters to options
+      choices << [ t(value['caption'], value['caption']), url_for( opts ) ] 
     end   
   end
   choices
@@ -503,10 +690,7 @@ end
 
 ############################################################################
 # Returns list of directories as array of choices for use in select field 
-# on folder permission form.
-# 
-# @example (as used in forms) 
-#   eval: dc_choices4_folders_list
+# on folder permission form. Directory root is determined from dc_site.files_directory field.
 ############################################################################
 def dc_choices4_folders_list
   public = File.join(Rails.root,'public')
@@ -518,32 +702,56 @@ def dc_choices4_folders_list
 end
 
 ############################################################################
-# Returns choices for select input filed.
+# Returns choices for select input field when choices can be generated from
+# all documents in collection.
 # 
-# @example 
-#   dc_choices4('dc_mail_list', 'name', '_id', :site_only => true)
-#   
-# @param [ model ] table (collection) model name.
-# @param [ name ] field name with description
-# @param [ id ] field name with id field. Default value is '_id'
-#      
+# Parameters:  
+# [model] String. Collection (table) name in lowercase format.
+# [name] String. Field name containing description text.
+# [id] String. Field name containing id field. Default is '_id'
+# [options] Hash. Various options. Currently site_only is used. Will return only 
+# documents belonging to current site.
+# 
+# Example (as used in forms):
+#    50:
+#      name: dc_poll_id
+#      type: select
+#      eval: dc_choices4('dc_poll','name','_id')
 ############################################################################
 def dc_choices4(model, name, id='_id', options = {})
   qry = model.classify.constantize.only(id, name).sort(name => 1)
   qry = qry.where(dc_site_id: dc_get_site()) if options[:site_only]
-  r = []
-  qry.each {|v| r << [ v[name], v[id] ] }
-  r
+  choices = []
+  qry.each {|v| choices << [ v[name], v[id] ] }
+  choices
 end
 
 ############################################################################
-# Adds new key to record cookie, thus preparing some initial values for creating 
-# new record on the next call.
+# Returns list of choices for selection top level menu on dc_page form. Used for defining which 
+# top level menu will be highlited when page is displayed.
 # 
-# @example 
-#   dc_add2_record_cookie(hash)
-#   
-# @param [ hash ] hash of cookies to add
+# Example (as used in forms):
+#    20:
+#      name: menu_id
+#      type: select
+#      eval: dc_choices4_menu      
+############################################################################
+def dc_choices4_menu
+  m_clas = dc_get_site.menu_class
+  m_clas = 'DcSimpleMenu' if m_clas.blank?
+  klass  = m_clas.classify.constantize
+  klass.choices4_menu(dc_get_site)
+end
+
+############################################################################
+# Will add data to record cookie. Record cookie is used to preload some 
+# data on next create action. Create action will look for cookies[:record] and 
+# if found initialize fields on form with matching name to value found in cookie data.
+# 
+# Example:
+#    kukis = {'dc_page.dc_design_id' => @page.dc_design_id,
+#             'dc_page.dc_menu_id' => @page.menu_id)
+#   dc_add2_record_cookie(kukis)
 ############################################################################
 def dc_add2_record_cookie(hash)
   kukis = if @parent.cookies[:record] and @parent.cookies[:record].size > 0
@@ -556,16 +764,23 @@ def dc_add2_record_cookie(hash)
 end
 
 ############################################################################
-# Returns true if access_policy allows user to view cms part 
-# Returns false and message if access is not allowed
+# Will check if user roles allow user to view data in document with defined access_policy.
 # 
-# @example 
-#   dc_user_can_view(@parent, @page)
-#   dc_user_can_view(@parent, @page.policy_id)
+# Parameters:
+# [ctrl] Controller object or object which holds methods to access session object. For example @parent
+# variable when called from renderer.
+# [policy_id] Document or documents policy_id field value required to view data. Method will automatically 
+# check if parameter send has policy_id field defined and use value of that field.
 # 
-# @param [ ctrl ] Controller object or object which holds methods to access session.
-# @param [ policy_id ] Policy id to check. If record is send as parameter, method will
-# check for policy_id field and use that field.
+# Example:
+#    can_view, message = dc_user_can_view(@parent, @page) 
+#    # or
+#    can_view, message = dc_user_can_view(@parent, @page.policy_id)
+#    return message unless can_view
+# 
+# Returns:
+# True if access_policy allows user to view data. 
+# False and message from policy that is blocking view if access is not allowed.
 ############################################################################
 def dc_user_can_view(ctrl, policy_id)
   policy_id = policy_id.policy_id if policy_id and policy_id.respond_to?(:policy_id)
@@ -577,6 +792,7 @@ def dc_user_can_view(ctrl, policy_id)
 # permission defined by default policy
   default_policy = policies.find_by(is_default: true)
   return false, 'Default accsess policy not found for the site!' unless default_policy
+#  
   h = {}
   default_policy.dc_policy_rules.to_a.each { |v| h[v.dc_policy_role_id] = v.permission }
 # update permissions with defined policy 
@@ -609,13 +825,21 @@ def dc_user_can_view(ctrl, policy_id)
 end
 
 ####################################################################
-# Return true if user has required role.
-# @example 
-#   dc_user_has_role('decision_maker', session[:user_id), session[:user_roles]) => true
+# Check if user has required role assigned to its user profile. If role is passed as
+# string method will check roles for name and system name.
 # 
-# @param [ role ] Role. Can be passed as string or role object. 
-# @param [ user ] User id. If not passed session[:user_id] will be used.
-# @param [ roles ] Array of roles that will be searched. If not passed session[:user_roles] will be used.
+# Parameters:
+# [role] DcPolicyRole/String. Required role. If passed as string role will be searched in dc_policy_roles collection.
+# [user] User id. Defaults to session[:user_id].
+# [roles] Array of roles that will be searched. Default session[:user_roles].
+# 
+# Example:
+#    if dc_user_has_role('decision_maker', session[:user_id), session[:user_roles]) 
+#      do_something_important
+#    end
+#    
+# Returns:
+# Boolean. True if user has required role.    
 ####################################################################
 def dc_user_has_role( role, user=nil, roles=nil )
   if roles.nil?
@@ -640,12 +864,13 @@ end
 # Returns true if parameter has value of 0, false, no or -. Returns default
 # if parameter has nil value.
 # 
-# @example 
-#   dc_dont?('no')  => true
-#   dc_dont?(1)     => false
+# Parameters:
+# [what] String/boolean. 
+# [default] Default value when what has value of nil. False by default.
 # 
-# @param [ string ] String to be examined
-# @param [ default ] Default value when not set. false by default.
+# Example:
+#    dc_dont?('no')  # => true
+#    dc_dont?(1)     # => false
 ####################################################################
 def dc_dont?(what, default=false)
   return default if what.nil?
@@ -653,13 +878,18 @@ def dc_dont?(what, default=false)
 end
 
 ############################################################################
-# Truncates string to the size and takes care, that words are not broken.
+# Truncates string length maximal to the size required and takes care, that words are not broken in middle.
+# Used for output text summary with texts that can be longer then allowed space.
 # 
-# @example 
-#   dc_limit_string(description, 100)
+# Parameters:
+# [string] String of any size.
+# [size] Maximal size of the string to be returned. 
 # 
-# @param [ string ] Input string
-# @param [ size ] Maximal size of the string
+# Example:
+#    dc_limit_string(description, 100)
+#    
+# Returns:
+# String, truncated to required size. If string is truncated '...' will be added to the end.
 ############################################################################
 def dc_limit_string(string, size)
   return string if string.size < size
@@ -669,14 +899,21 @@ def dc_limit_string(string, size)
 end
 
 ############################################################################
-# Returns key defined in BigTable as array of choices for use in select fields.
-# It first checks if key is defined only for current site and then if site 
-# is not defined. 
+# Returns key defined in DcBigTable as array of choices for use in select fields.
+# DcBigTable can be used like a key/value store for all kind of predefined values 
+# which can be linked to site and or locale.
+# 
+# Parameters:
+# [key] String. Key name to be searched in dc_big_tables documents.
 # 
-# @example 
-#   eval: dc_big_table 'some-key'  # as used on form
+# Example:
+#    10:
+#      name: category
+#      type: select
+#      eval: dc_big_table 'categories_for_page'  # as used on form
 # 
-# @param [ string ] Key to be returned
+# Returns:
+# Array of choices ready for select field.
 ############################################################################
 def dc_big_table(key)
   ret = []