Merge pull request #26 from jekyll/page-dot-date

Move Date object from `page.title` to `page.date`

Author: alfredxing

docs/layouts.md

@@ -1,10 +1,13 @@
 # Layouts
 
-Archives layouts are special layouts that specify how an archive page is displayed. Special attributes are available to these layouts to represent information about the specific layout being generated. These layouts are otherwise identical to regular Jekyll layouts.
+Archives layouts are special layouts that specify how an archive page is displayed. Special attributes are available to these layouts to represent information about the specific layout being generated. These layouts are otherwise identical to regular Jekyll layouts. To handle the variety of cases presented through the attributes, we recommend that you use [type-specific layouts](./configuration.md#type-specific-layouts). 
 
 ### Layout attributes
 #### Title (`page.title`)
-The `page.title` attribute contains information regarding the name or header of the archive. For tag and category archives, this is simply the name of the tag/category. For date-based archives (year, month, and day), this attribute contains a Date object that can be used to present the date header of the archive in a suitable format. For year archives, the month and day components of the Date object passed to Liquid should be neglected; similarly, for month archives, the day component should be neglected. To handle the variety of cases presented, we recommend that you use [type-specific layouts](./configuration.md#type-specific-layouts). We recommend using the [`date` filter](http://docs.shopify.com/themes/liquid-documentation/filters/additional-filters#date) in Liquid to process the Date objects.
+The `page.title` attribute contains information regarding the name of the archive *if and only if* the archive is a tag or category archive. In this case, the attribute simply contains the name of the tag/category. For date-based archives (year, month, and day), this attribute is `nil`.
+
+#### Date (`page.date`)
+In the case of a date archive, this attribute contains a Date object that can be used to present the date header of the archive in a suitable format. For year archives, the month and day components of the Date object passed to Liquid should be neglected; similarly, for month archives, the day component should be neglected. We recommend using the [`date` filter](http://docs.shopify.com/themes/liquid-documentation/filters/additional-filters#date) in Liquid to process the Date objects. For tag and category archives, this field is `nil`.
 
 #### Posts (`page.posts`)
 The `page.posts` attribute contains an array of Post objects matching the archive criteria. You can iterate over this array just like any other Post array in Jekyll.

lib/jekyll-archives/archive.rb

@@ -13,6 +13,7 @@ class Archive
         posts
         type
         title
+        date
         name
         path
         url
@@ -116,14 +117,21 @@ def to_liquid(attrs = nil)
 
       # Produce a title object suitable for Liquid based on type of archive.
       #
-      # Returns the title as a Date (for date-based archives) or a
-      # String (for tag and category archives)
+      # Returns a String (for tag and category archives) and nil for
+      # date-based archives.
       def title
+        if @title.is_a? String
+          @title
+        end
+      end
+
+      # Produce a date object if a date-based archive
+      #
+      # Returns a Date.
+      def date
         if @title.is_a? Hash
           args = @title.values.map { |s| s.to_i }
           Date.new(*args)
-        else
-          @title
         end
       end
 

test/test_jekyll_archives.rb

@@ -158,4 +158,43 @@ class TestJekyllArchives < Minitest::Test
       assert !archive_exists?(@site, "category/plugins/index.html")
     end
   end
+
+  context "the jekyll-archives plugin" do
+    setup do
+      @site = fixture_site({
+        "jekyll-archives" => {
+          "enabled" => true
+        }
+      })
+      @site.process
+      @archives = @site.config["archives"]
+      @tag_archive = @archives.detect {|a| a.type == "tag"}
+      @category_archive = @archives.detect {|a| a.type == "category"}
+      @year_archive = @archives.detect {|a| a.type == "year"}
+      @month_archive = @archives.detect {|a| a.type == "month"}
+      @day_archive = @archives.detect {|a| a.type == "day"}
+    end
+
+    should "populate the title field in case of category or tag" do
+      assert @tag_archive.title.is_a? String
+      assert @category_archive.title.is_a? String
+    end
+
+    should "use nil for the title field in case of dates" do
+      assert @year_archive.title.nil?
+      assert @month_archive.title.nil?
+      assert @day_archive.title.nil?
+    end
+
+    should "use nil for the date field in case of category or tag" do
+      assert @tag_archive.date.nil?
+      assert @category_archive.date.nil?
+    end
+
+    should "populate the date field with a Date in case of dates" do
+      assert @year_archive.date.is_a? Date
+      assert @month_archive.date.is_a? Date
+      assert @day_archive.date.is_a? Date
+    end
+  end
 end