From 1902c4bf975a5c1decd199a5190b04d08a2e4760 Mon Sep 17 00:00:00 2001
From: hukl <hukl@eight.intern.artcom.de>
Date: Tue, 3 Feb 2009 16:47:43 +0100
Subject: added lots of comments to describe what the methods are doing. this
 will get everyone a better start. I hope

---
 app/controllers/content_controller.rb |  7 ++++++-
 app/helpers/content_helper.rb         | 18 ++++++++++++++++++
 app/models/node.rb                    |  1 +
 app/models/page.rb                    | 14 +++++++-------
 lib/awesome_patch.rb                  |  1 -
 5 files changed, 32 insertions(+), 9 deletions(-)

diff --git a/app/controllers/content_controller.rb b/app/controllers/content_controller.rb
index 278c5ab..0fa9832 100644
--- a/app/controllers/content_controller.rb
+++ b/app/controllers/content_controller.rb
@@ -1,5 +1,10 @@
 class ContentController < ApplicationController
-
+  
+  # This is the method that renders most of the the public content. It recieves
+  # a :locale and a :page_path parameter through the params hash. It looks up 
+  # the node with the corresponding unique_name attribute. The method doesn't
+  # return a node though, the node is really a proxy object for pages. It 
+  # returns the most recent page associated to this node instead.
   def render_page
     path = params[:page_path].join('/')
     
diff --git a/app/helpers/content_helper.rb b/app/helpers/content_helper.rb
index 385bca0..9800471 100644
--- a/app/helpers/content_helper.rb
+++ b/app/helpers/content_helper.rb
@@ -1,9 +1,25 @@
 module ContentHelper
   
+  # Returns the published_at attribute of a page if it is not nil, otherwise
+  # it returns the auto-filled value of the created_at attribute
   def date_for_page page
     page.published_at.to_s(:db) rescue page.created_at.to_s(:db)
   end
   
+  # This method is an output filter for templates. It accepts any kind of text
+  # and checks for an <aggregate /> tag within it. If such a tag is found, its 
+  # attributes are parsed and converted into parameters for the 
+  # render_collection method. The <aggregate /> tag will then be replaced 
+  # entirely with the output of the render_collection method.
+  #
+  # Syntax of the <aggregate /> tag:
+  #
+  # <aggregate 
+  #   flags="update, pressemitteilung"
+  #   limit="20"
+  #   order_by="published_at"
+  #   order_direction="DESC"
+  # />
   def aggregate? content
     options = {}
     
@@ -27,6 +43,8 @@ module ContentHelper
     end
   end
   
+  # Takes the parameters from the aggregate? method and renders the collection
+  # from Page.aggregate(options) with a given partial
   def render_collection options
     render(
       :partial => 'content/article', 
diff --git a/app/models/node.rb b/app/models/node.rb
index 3564ce4..0aa28b9 100644
--- a/app/models/node.rb
+++ b/app/models/node.rb
@@ -40,5 +40,6 @@ class Node < ActiveRecord::Base
   def update_unique_name
     path = self.path_to_root[1..-1]
     self.unique_name = path.join("/")
+    self.save
   end
 end
diff --git a/app/models/page.rb b/app/models/page.rb
index f6c5ef2..d33e11b 100644
--- a/app/models/page.rb
+++ b/app/models/page.rb
@@ -4,13 +4,13 @@ class Page < ActiveRecord::Base
 
   acts_as_taggable  
   acts_as_list :column => :revision, :scope => :node_id
-
-  # <aggregate 
-  #   flags="update, pressemitteilung"
-  #   limit="20"
-  #   order_by="published_at"
-  #   order_direction="DESC"
-  # />
+  
+  # This method is most likely called from the ContentHelper.render_collection
+  # method which aggregates pages into a collection, based on parameters it 
+  # recieves. This method then calls Page.aggregate with these parameters.
+  # The Page.aggregate method comes with a defaults hash. These options are
+  # partially or entirely overwritten by the options hash. Afterwards the merged
+  # parameters are used to query the DB for Pages matching these parameters.
   def self.aggregate options
     
     defaults = {
diff --git a/lib/awesome_patch.rb b/lib/awesome_patch.rb
index 1694ccf..d9f738c 100644
--- a/lib/awesome_patch.rb
+++ b/lib/awesome_patch.rb
@@ -8,7 +8,6 @@ module CollectiveIdea
           move_to_original target, position
           if self.class == Node
             self.update_unique_name
-            self.save
           end
         end
       end
-- 
cgit v1.3