drg_cms 0.4.39 → 0.4.53

data/app/models/dc_key_value_store.rb

@@ -21,6 +21,15 @@
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #++
 
+#########################################################################
+# Mongoid::Document model for dc_key_value_stores collection. 
+# 
+# This model represents key/value store. Typical usage is for saving last
+# used document number on some internal document numbering schema.
+# 
+# Example: 
+#    doc_number = DcKeyValueStore.get_next_value('invoices', invoice_date.year)
+#########################################################################
 class DcKeyValueStore
   include Mongoid::Document
   
@@ -31,6 +40,12 @@ class DcKeyValueStore
 
 ###########################################################################
 # Will return value incremented by 1 and update document with new value.
+# 
+# Parameters: 
+# [keys] Array. Any number of parameters from which key will be generated.
+# 
+# Returns:
+# String. Last saved value incremented by 1.
 ###########################################################################
 def self.get_next_value(*keys)
   doc   = find_by(key: keys.join('-'))
@@ -46,8 +61,12 @@ end
 
 ###########################################################################
 # Will try to restore to previous value if value is not already incremented.
+# 
+# Parameters: 
+# [value] String. Last value obtained by get_next_value method.
+# [keys] Array. Any number of parameters from which key will be generated.
 ###########################################################################
-def self.restore_value(value,*keys)
+def self.restore_value(value, *keys)
   doc = find_by(key: keys.join('-'))
   if value == doc.value
     value = (value.to_i - 1).to_s
@@ -59,7 +78,15 @@ def self.restore_value(value,*keys)
 end
 
 ###########################################################################
-#
+# Will return value incremented by 1 but will not update document with new value.
+# Used for presenting user with most possible document number. Real document number must
+# of course be obtained by get_next_value before document is saved to collection.
+# 
+# Parameters: 
+# [keys] Array. Any number of parameters from which key will be generated.
+# 
+# Returns:
+# String. Last saved value incremented by 1.
 ###########################################################################
 def self.peep_next_value(*keys)
   doc = find_by(key: keys.join('-'))
@@ -67,7 +94,13 @@ def self.peep_next_value(*keys)
 end
 
 ###########################################################################
-#
+# Will return current value for the key.
+# 
+# Parameters: 
+# [keys] Array. Any number of parameters from which key will be generated.
+# 
+# Returns:
+# String. Current value for specified key or nil if key is not found.
 ###########################################################################
 def self.get_value(*keys)
   doc = find_by(key: keys.join('-'))
@@ -75,7 +108,11 @@ def self.get_value(*keys)
 end
 
 ###########################################################################
-#
+# Will set value for the key. If document is not found new document will be created.
+# 
+# Parameters: 
+# [value] String. New value to be set.
+# [keys] Array. Any number of parameters from which key will be generated.
 ###########################################################################
 def self.set_value(value, *keys)
   doc = find_by(key: keys.join('-'))

data/app/models/dc_link.rb

@@ -20,6 +20,13 @@
 # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #++
+
+#########################################################################
+# Mongoid::Document model for dc_links collection. 
+# 
+# DcLink documents may be used for creating alternative url links. page_id field must 
+# point to valid DcPage document which will be used for further processing. 
+#########################################################################
 class DcLink
   include Mongoid::Document
   include Mongoid::Timestamps

data/app/models/dc_menu.rb

@@ -20,6 +20,14 @@
 # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #++
+
+#########################################################################
+# Mongoid::Document model for dc_menus collection. 
+# 
+# Default menu system for DRG CMS. Model recursively embeds DcMenuItem documents
+# which (theoretically) results in infinite level of sub menus. In practice 
+# reasonable maximum level of 4 is advised.
+#########################################################################
 class DcMenu
   include Mongoid::Document
   include Mongoid::Timestamps
@@ -41,15 +49,24 @@ class DcMenu
   validates_length_of :description, minimum: 10
   
 #######################################################################
-#
+# Will return all top level menu items of specified menu. Used in DcPage document for
+# selecting top level selected menu, when document displayed in browser.
+# 
+# Called from DcApplicationHelper :dc_choices4_menu: method.
+# 
+# Parameters: 
+# [Site] DcSite document. Site for which menu belongs to. If site is not specified 
+# all current menus in dc_menus collection will be returned.
+# 
+# Returns:
+# Array. Of choices prepared for select input field.
 #######################################################################
   def self.choices4_menu(site)
   rez = []
   menus = (site.menu_name.blank? ? all : where(name: site.menu_name)).to_a
   menus.each do |menu|
     rez << [menu.name, nil]
-    menu.dc_menu_items.where(active: true).order_by(:order => 1).each do |menu_item|
-#      next unless menu_item.active
+    menu.dc_menu_items.where(active: true).order_by(order: 1).each do |menu_item|
       rez << ['-- ' + menu_item.caption, menu_item._id]
     end
   end

data/app/models/dc_menu_item.rb

@@ -20,6 +20,13 @@
 # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #++
+
+#########################################################################
+# Mongoid::Document model for dc_menu_items embedded documents. 
+# 
+# DcMenuItem documents are embedded in the DcMenu document and define one menu
+# item of menu system. 
+#########################################################################
 class DcMenuItem
   include Mongoid::Document
   include Mongoid::Timestamps

data/app/models/dc_page.rb

@@ -22,7 +22,10 @@
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #++
 
-module DcPageCommon
+#########################################################################
+# ActiveSupport::Concern definition for DcPage class. 
+#########################################################################
+module DcPageConcern
 extend ActiveSupport::Concern
 included do
   
@@ -56,6 +59,8 @@ field :kats,         type: Array         # Categories
 field :policy_id,    type: BSON::ObjectId
 
 embeds_many :dc_parts
+#embeds_many :dc_parts, as: :dc_parts
+
 
 belongs_to  :dc_site
 belongs_to  :dc_design
@@ -68,13 +73,12 @@ before_save :do_before_save
 
 validates :publish_date, presence: true
   
-######################################################################
-#
 ######################################################################
 protected
 
 ######################################################################
-# Clears subject link of chars that shouldn't be there and also take care of its size
+# Clears subject link of chars that shouldn't be there and also takes care 
+# than link size is not larger than 100 chars.
 ######################################################################
 def clear_link(link)
   link.gsub!(/\.|\?|\!\&|»|«|\,|\"|\'|\:/,'')
@@ -92,7 +96,7 @@ def clear_link(link)
 end
 
 ######################################################################
-#
+# Implementation of before_save callback.
 ######################################################################
 def do_before_save
   if self.subject_link.empty?
@@ -102,10 +106,12 @@ def do_before_save
   end
 end
 
-################################################################################
-
 ######################################################################
-# Return all pages belonging to site ready for select input field.
+# Return all pages belonging to site ready for select input field. Used
+# by dc_menu* forms, for selecting page which will be linked by menu option.
+# 
+# Parameters:
+# [site] Site document.
 ######################################################################
 def self.all_pages_for_site(site)
   where(dc_site_id: site._id, active: true).order(subject: 1).
@@ -115,9 +121,22 @@ end
 end
 end
 
-######################################################################
-#
-######################################################################
+#########################################################################
+# Mongoid::Document model for dc_page documents. 
+# 
+# DcPage documents are anchors for urls. Default DcApplicationController::dc_process_default_request() 
+# method searches for DcPage document by subject_link, id or alt_link. When found it loads 
+# design document defined by design_id and renders view code defined by design. 
+# 
+# Site owner has all control of how DcPage data is rendered by providing its own page renderer methods.
+# 
+# Every DcPage document may embed many DcPart documents. DcPart documents mostly contain fields
+# with same names and functionality as DcPage fields. And may therefore represent whole subpage data
+# system within single document. Clever programmer may provide data for whole web site in just 
+# one DcSite, one DcMenu, one DcDesign and one DcPage document (with some embedded documents). And since 
+# DRG runs multiple sites on single Rails instance by default, may run hundreds of small sites
+# on single Rails instance.
+#########################################################################
 class DcPage
-  include DcPageCommon
+  include DcPageConcern
 end

data/app/models/dc_part.rb

@@ -20,9 +20,39 @@
 # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #++
-class DcPart < DcPiece
-  embedded_in :dc_design
-  embedded_in :dc_page
+require_dependency DrgCms.model 'dc_piece'
+
+########################################################################
+# Mongoid::Document model for dc_part embedded documents.
+# 
+# DcPart model is used for embedding parts of final document into other models. It declares fields
+# which may be used in various scenarios. For example:
+# - part of page which is visible to all users and part only to registered users
+# - list of pictures or attachments which belong to document 
+# -
+# 
+# DcPart model inherits its definition from DcPiece model, but adds policy_id
+# field to definition. Policy_id field may be used where site policy must be 
+# taken into account when rendering part.
+########################################################################
+class DcPart 
+  include DcPieceConcern
+  
+  field :_type,       type: String, default: 'DcPart' # needed when changed to Concern
+  field :policy_id,   type: BSON::ObjectId
+  field :link,        type: String
+  
+  embedded_in :dc_parts, polymorphic: true
+  
+  before_save :do_before_save
+  
+######################################################################
+# Implementation of before_save callback.
+######################################################################
+def do_before_save
+  if self.link.empty?
+    self.link = self.name.strip.downcase.gsub(' ','-')
+  end
+end
   
-  field :policy_id,     type: BSON::ObjectId
 end

data/app/models/dc_permission.rb

@@ -21,20 +21,36 @@
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #++
 
-#########################################################################
-#
+########################################################################
+# Mongoid::Document model for dc_permissions collection.
+# 
+# dc_permissions collection is used for saving documents which define permissions 
+# for accessing individual collections within DRG CMS system. Document which is marked 
+# as default is the top level document and defines general permissions valid for
+# all collections. Other documents define permissions for accessing single
+# collections or even embedded documents within collections.
 #########################################################################
 class DcPermission
-# Declaration of permissions
-NO_ACCESS     = 0
-CAN_VIEW      = 1
-CAN_CREATE    = 2
-CAN_EDIT      = 4
-CAN_EDIT_ALL  = 8
-CAN_DELETE    = 16
+#- Available permissions settings
+
+# User has no access 
+NO_ACCESS     = 0 
+# User can view documents
+CAN_VIEW      = 1 
+# User can create new documents  
+CAN_CREATE    = 2 
+# User can edit his own documents
+CAN_EDIT      = 4 
+# User can edit all documents in collection
+CAN_EDIT_ALL  = 8 
+# User can delete his own documents
+CAN_DELETE    = 16 
+# User can delete all documents in collection
 CAN_DELETE_ALL = 32
-CAN_ADMIN     = 64
-SUPERADMIN    = 128
+# User can admin collection (same as can_delete_all, but can see documents which do not belong to current site)
+CAN_ADMIN     = 64 
+# User is superadmin. Basicly same as admin.
+SUPERADMIN    = 128 
 
 include Mongoid::Document
 include Mongoid::Timestamps
@@ -51,7 +67,11 @@ index( { table_name: 1 }, { unique: true } )
 validates :table_name, presence: true
 validates :table_name, uniqueness: true  
 
-def self.values_for_permissions
+########################################################################
+# Will return choices for permissions prepared for usega in select input field.
+# This will return english only comments so it is not used.
+########################################################################
+def self.values_for_permissions #:nodoc:
   [['NO_ACCESS',0],['CAN_VIEW',1],['CAN_CREATE',2],['CAN_EDIT',4],['CAN_EDIT_ALL',8],['CAN_DELETE',16],['CAN_DELETE_ALL',32],['CAN_ADMIN',64],['SUPERADMIN',128]]
 end
 

data/app/models/dc_piece.rb

@@ -20,7 +20,15 @@
 # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #++
-class DcPiece 
+
+
+#########################################################################
+# ActiveSupport::Concern definition for DcPiece class. 
+#########################################################################
+module DcPieceConcern
+  extend ActiveSupport::Concern
+  included do
+  
   include Mongoid::Document
   include Mongoid::Timestamps
 
@@ -44,14 +52,34 @@ class DcPiece
   field :created_by,    type: BSON::ObjectId
   field :updated_by,    type: BSON::ObjectId  
   
+  validates :name, presence: true
+end
+end
+
+########################################################################
+# Mongoid::Document model for dc_piece documents.
+# 
+# DcPiece model is used for documents or pieces of web site which are common to site 
+# or perhaps to all sites in database. For example page footer is a good candidate 
+# to be saved in a dc_piece collection.
+# 
+# Documents in dc_pieces collection must have unique name assigned. Default DcPartRenderer
+# also looks into dc_pieces collection and collects all documents which belong to
+# current site (site_id field) and renders them according to div_id field value.
+########################################################################
+class DcPiece 
+  include DcPieceConcern
+
   index( { name: 1 }, { unique: true } )  
-  index( { site_id: 1 } )  
+  index( { site_id: 1 } ) 
+  
+  validates :name, uniqueness: true  
   
 ########################################################################
-# Return choices for select for dc_policy_role_id
+# Return choices for select for selecting documents on dc_part form.
 ########################################################################
 def self.choices4_pieces
   all.inject([]) { |r,piece| r << [ piece.name, piece._id] }
 end
   
-end
+end

data/app/models/dc_policy.rb

@@ -21,8 +21,15 @@
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #++
 
-#########################################################################
-#
+########################################################################
+# Mongoid::Document model for dc_policy documents embedded into dc_sites collection documents.
+# 
+# DcPolicy documents define policies for accessing data on web site. Policies define which 
+# user roles (defined in dc_policy_roles collection) has no access, can view or edit data (sees CMS menu) on
+# current active web page. Policies can then be applied to individual documents belonging to the web site.
+# 
+# Document defined as default, holds top level policy which is inherited by all
+# other policies. Default policy is also used when document has no access policy assigned.
 #########################################################################
 class DcPolicy
   include Mongoid::Document
@@ -35,25 +42,23 @@ class DcPolicy
   field :updated_by,  type: BSON::ObjectId
   field :message,     type: String,  default: ''
   
-  #embeds_many :dc_policy_rules
   embeds_many :dc_policy_rules, as: :policy_rules  
   embedded_in :dc_site
 
   validates :name, :length => { :minimum => 4 }  
   validates :message, :length => { :minimum => 5 }  
   
-#  index name: 1
-#  index 'dc_policy_rules._id' => 1
-  
+=begin  
 #########################################################################
-#
+# Returns values for permissions ready to be used in select field.
 #########################################################################
-def self.values_for_permissions
+def self.values_for_permissions 
   [['NO_ACCESS',0],['CAN_VIEW',1],['CAN_CREATE',2],['CAN_EDIT',4],['CAN_EDIT_ALL',8],['CAN_DELETE',16],['CAN_DELETE_ALL',32],['CAN_ADMIN',64],['SUPERADMIN',128]]
 end
 
+  
 #########################################################################
-# returns all possible policy rules for use in select input field
+# Returns all possible policy rules for use in select input field
 #########################################################################
 def self.choices4_policies()
   rez = []
@@ -65,7 +70,7 @@ def self.choices4_policies()
   end
   rez
 end
-
+  
 #########################################################################
 # Returns policy rules for the site. Since it is called from policy_role form
 # which can be embedded in lots of tables (collections) table name of parent 
@@ -90,5 +95,6 @@ def self.policy_rule_name_for(id)
   return 'Invalid policy name!' if pol.nil?
   pol.dc_policy_rules.find(id).name
 end
-
+=end
+  
 end