Module: Nanoc::Helpers::Blogging
- Included in:
- AtomFeedBuilder
- Defined in:
- lib/nanoc/helpers/blogging.rb
Overview
Provides functionality for building blogs, such as finding articles and constructing feeds.
This helper has a few requirements. First, all blog articles should have the following attributes:
-
kind
- Set to"article"
-
created_at
- The article’s publication timestamp
Some functions in this blogging helper, such as the #atom_feed function, require additional attributes to be set; these attributes are described in the documentation for these functions.
All “time” item attributes, site configuration attributes or method
parameters can either be a Time
instance or a string in any format
parseable by Time.parse
.
The two main functions are #sorted_articles and #atom_feed.
Defined Under Namespace
Classes: AtomFeedBuilder
Instance Method Summary collapse
-
#articles ⇒ Array
Returns an unsorted list of articles, i.e.
-
#atom_feed(params = {}) ⇒ String
Returns a string representing the atom feed containing recent articles, sorted by descending creation date.
-
#atom_tag_for(item) ⇒ String
Returns an URI containing an unique ID for the given item.
-
#attribute_to_time(arg) ⇒ Time
Converts the given attribute (which can be a string, a Time, a Date or a DateTime) into a Time.
-
#feed_url ⇒ String
Returns the URL of the feed.
-
#sorted_articles ⇒ Array
Returns a sorted list of articles, i.e.
-
#url_for(item) ⇒ String
Returns the URL for the given item.
Instance Method Details
#articles ⇒ Array
Returns an unsorted list of articles, i.e. items where the kind
attribute is set to "article"
.
26 27 28 29 30 31 32 33 |
# File 'lib/nanoc/helpers/blogging.rb', line 26 def articles blk = -> { @items.select { |item| item[:kind] == 'article' } } if @items.frozen? @article_items ||= blk.call else blk.call end end |
#atom_feed(params = {}) ⇒ String
Returns a string representing the atom feed containing recent articles, sorted by descending creation date.
The following attributes must be set on blog articles:
-
title
- The title of the blog post -
created_at
(described above) -
kind
(described above) unless you are passing an explicit list of articles using the:articles
parameter
The following attributes can optionally be set on blog articles to change the behaviour of the Atom feed:
-
excerpt
- An excerpt of the article, which is usually only a few lines long. -
custom_path_in_feed
- The path that will be used instead of the normal path in the feed. This can be useful when including non-outputted items in a feed; such items could have their custom feed path set to the blog path instead, for example. -
custom_url_in_feed
- The url that will be used instead of the normal url in the feed (generated from the site’s base url + the item rep’s path). This can be useful when building a link-blog where the URL of article is a remote location. -
updated_at
- The time when the article was last modified. If this attribute is not present, thecreated_at
attribute will be used as the time when the article was last modified.
The site configuration will need to have the following attributes:
base_url
- The URL to the site, without trailing slash. For example, if the site is at “http://example.com/”, thebase_url
would be “http://example.com”.
The feed item will need to know about the feed title, the feed author name, and the URI corresponding to the author. These can be specified using parameters, as attributes in the feed item, or in the site configuration.
-
title
- The title of the feed, which is usually also the title of the blog. -
author_name
- The name of the item’s author. -
author_uri
- The URI for the item’s author, such as the author’s web site URL.
The feed item can have the following optional attributes:
feed_url
- The custom URL of the feed. This can be useful when the private feed URL shouldn’t be exposed; for example, when using FeedBurner this would be set to the public FeedBurner URL.
To construct a feed, create a new item and make sure that it is
filtered with :erb
or :erubis
; it should not be laid out. Ensure
that it is routed to the proper path, e.g. /blog.xml
. It may also be
useful to set the is_hidden
attribute to true, so that helpers such
as the sitemap helper will ignore the item. The content of the feed
item should be <%= atom_feed %>
.
305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 |
# File 'lib/nanoc/helpers/blogging.rb', line 305 def atom_feed(params = {}) require 'builder' # Create builder builder = AtomFeedBuilder.new(@config, @item) # Fill builder builder.limit = params[:limit] || 5 builder.relevant_articles = params[:articles] || articles || [] builder.preserve_order = params.fetch(:preserve_order, false) builder.content_proc = params[:content_proc] || ->(a) { a.compiled_content(snapshot: :pre) } builder.excerpt_proc = params[:excerpt_proc] || ->(a) { a[:excerpt] } builder.title = params[:title] || @item[:title] || @config[:title] builder. = params[:author_name] || @item[:author_name] || @config[:author_name] builder. = params[:author_uri] || @item[:author_uri] || @config[:author_uri] builder.icon = params[:icon] builder.logo = params[:logo] # Run builder.validate builder.build end |
#atom_tag_for(item) ⇒ String
Returns an URI containing an unique ID for the given item. This will be used in the Atom feed to uniquely identify articles. These IDs are created using a procedure suggested by Mark Pilgrim and described in his [“How to make a good ID in Atom” blog post] (http://web.archive.org/web/20110915110202/http://diveintomark.org/archives/2004/05/28/howto-atom-id).
372 373 374 375 376 377 378 |
# File 'lib/nanoc/helpers/blogging.rb', line 372 def atom_tag_for(item) hostname, base_dir = %r{^.+?://([^/]+)(.*)$}.match(@config[:base_url])[1..2] formatted_date = attribute_to_time(item[:created_at]).__nanoc_to_iso8601_date 'tag:' + hostname + ',' + formatted_date + ':' + base_dir + (item.path || item.identifier.to_s) end |
#attribute_to_time(arg) ⇒ Time
Converts the given attribute (which can be a string, a Time, a Date or a DateTime) into a Time. When given a Date instance or a string, the argument is assumed to be in the local timezone.
388 389 390 391 392 393 394 395 396 397 398 399 |
# File 'lib/nanoc/helpers/blogging.rb', line 388 def attribute_to_time(arg) case arg when DateTime arg.to_time when Date Time.local(arg.year, arg.month, arg.day) when String Time.parse(arg) else arg end end |
#feed_url ⇒ String
Returns the URL of the feed. It will return the custom feed URL if set, or otherwise the normal feed URL.
354 355 356 357 358 359 360 361 |
# File 'lib/nanoc/helpers/blogging.rb', line 354 def feed_url # Check attributes if @config[:base_url].nil? raise Nanoc::Int::Errors::GenericTrivial.new('Cannot build Atom feed: site configuration has no base_url') end @item[:feed_url] || @config[:base_url] + @item.path end |
#sorted_articles ⇒ Array
Returns a sorted list of articles, i.e. items where the kind
attribute is set to "article"
. Articles are sorted by descending
creation date, so newer articles appear before older articles.
40 41 42 43 44 45 46 47 48 |
# File 'lib/nanoc/helpers/blogging.rb', line 40 def sorted_articles blk = -> { articles.sort_by { |a| attribute_to_time(a[:created_at]) }.reverse } if @items.frozen? @sorted_article_items ||= blk.call else blk.call end end |
#url_for(item) ⇒ String
Returns the URL for the given item. It will return the URL containing the custom path in the feed if possible, otherwise the normal path.
334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 |
# File 'lib/nanoc/helpers/blogging.rb', line 334 def url_for(item) # Check attributes if @config[:base_url].nil? raise Nanoc::Int::Errors::GenericTrivial.new('Cannot build Atom feed: site configuration has no base_url') end # Build URL if item[:custom_url_in_feed] item[:custom_url_in_feed] elsif item[:custom_path_in_feed] @config[:base_url] + item[:custom_path_in_feed] elsif item.path @config[:base_url] + item.path end end |