Module: Middleman::Blog::BlogArticle

Extended by:
Gem::Deprecate
Defined in:
lib/middleman-blog/blog_article.rb

Overview

A module that adds blog-article-specific methods to Resources. A BlogArticle can be retrieved via Helpers#current_article or methods on BlogData (like Middleman::Blog::BlogData#articles).

See Also:

Instance Method Summary collapse

Instance Method Details

#article_locale_next ⇒ Middleman::Sitemap::Resource

The next (chronologically later) article after this one in the current locale or nil if this is the most recent article.

Returns:

  • (Middleman::Sitemap::Resource) 


335
336
337
 
# File 'lib/middleman-blog/blog_article.rb', line 335

def article_locale_next
  blog_data.local_articles.reverse.find { |a| a.date > self.date }
end

#article_locale_previous ⇒ BlogArticle

The previous (chronologically earlier) article before this one in the current locale, or nil if this is the first article.

Returns:



325
326
327
 
# File 'lib/middleman-blog/blog_article.rb', line 325

def article_locale_previous
  blog_data.local_articles.find { |a| a.date < self.date }
end

#article_next ⇒ Middleman::Sitemap::Resource

The next (chronologically later) article after this one or nil if this is the most recent article.

Returns:

  • (Middleman::Sitemap::Resource) 


315
316
317
 
# File 'lib/middleman-blog/blog_article.rb', line 315

def article_next
  blog_data.articles.reverse.find { |a| a.date > self.date }
end

#article_previous ⇒ BlogArticle

The previous (chronologically earlier) article before this one or nil if this is the first article.

Returns:



305
306
307
 
# File 'lib/middleman-blog/blog_article.rb', line 305

def article_previous
  blog_data.articles.find { |a| a.date < self.date }
end

#blog_data ⇒ BlogData

A reference to the Middleman::Blog::BlogData for this article’s blog.

Returns:



33
34
35
 
# File 'lib/middleman-blog/blog_article.rb', line 33

def blog_data
  blog_controller.data
end

#blog_options ⇒ ConfigurationManager

The options for this article’s blog.

Returns:

  • (ConfigurationManager) 


42
43
44
 
# File 'lib/middleman-blog/blog_article.rb', line 42

def blog_options
  blog_controller.options
end

#body ⇒ String

The body of this article, in HTML (no layout). This is for things like RSS feeds or lists of articles - individual articles will automatically be rendered from their template.

Returns:

  • (String) 


103
104
105
 
# File 'lib/middleman-blog/blog_article.rb', line 103

def body
  render layout: false
end

#date ⇒ TimeWithZone

Attempt to figure out the date of the post. The date should be present in the source path, but users may also provide a date in the frontmatter in order to provide a time of day for sorting reasons.

Returns:

  • (TimeWithZone) 


215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
 
# File 'lib/middleman-blog/blog_article.rb', line 215

def date

  return @_date if @_date

  frontmatter_date = data['date']

  # First get the date from frontmatter
  if frontmatter_date.is_a? Time
    @_date = frontmatter_date.in_time_zone
  else
    @_date = Time.zone.parse(frontmatter_date.to_s)
  end

  # Next figure out the date from the filename
  source_vars = blog_data.source_template.variables

  if source_vars.include?('year') &&
     source_vars.include?('month') &&
     source_vars.include?('day')

    filename_date = Time.zone.local(path_part('year').to_i, path_part('month').to_i, path_part('day').to_i)
    if @_date
      raise "The date in #{path}'s filename doesn't match the date in its frontmatter" unless @_date.to_date == filename_date.to_date
    else
      @_date = filename_date.to_time.in_time_zone
    end

  end

  raise "Blog post #{path} needs a date in its filename or frontmatter" unless @_date

  @_date

end

#default_summary_generator(rendered, length, ellipsis) ⇒ Object

The default summary generator first tries to find the summary_separator and take the text before it. If that doesn’t work, it will truncate text without splitting the middle of an HTML tag, using a Nokogiri-based TruncateHTML utility.

Parameters:

  • rendered (String) —

    The rendered blog article

  • length (Integer) —

    The length in characters to truncate to. -1 or nil will return the whole article.

  • ellipsis (String) —

    The ellipsis string to use when content is trimmed.



144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
 
# File 'lib/middleman-blog/blog_article.rb', line 144

def default_summary_generator(rendered, length, ellipsis)

  if blog_options.summary_separator && rendered.match(blog_options.summary_separator)
    require 'middleman-blog/truncate_html'
    TruncateHTML.truncate_at_separator(rendered, blog_options.summary_separator)

  elsif length && length >= 0
    require 'middleman-blog/truncate_html'
    TruncateHTML.truncate_at_length(rendered, length, ellipsis)

  elsif blog_options.summary_length && blog_options.summary_length > 0
    require 'middleman-blog/truncate_html'
    TruncateHTML.truncate_at_length(rendered, blog_options.summary_length, ellipsis)

  else
    rendered
  end

end

#locale ⇒ Symbol Also known as: lang

The language of the article. The language can be present in the frontmatter or in the source path. If both are present, they must match. If neither specifies a lang, I18n’s default_locale will be used. If lang is set to nil, or the :i18n extension is not activated at all, nil will be returned.

Returns:

  • (Symbol) —

    Language code (for example, :en or :de)



190
191
192
193
194
195
196
197
198
199
200
201
202
203
 
# File 'lib/middleman-blog/blog_article.rb', line 190

def locale

  frontmatter_locale = data['locale'] || data['lang']
  filename_locale    = path_part('locale') || path_part('lang')

  if frontmatter_locale && filename_locale && frontmatter_locale != filename_locale
    raise "The locale in #{path}'s filename (#{filename_locale.inspect}) doesn't match the lang in its frontmatter (#{frontmatter_locale.inspect})"
  end

  default_locale = I18n.default_locale if defined? ::I18n

  found_locale = frontmatter_locale || filename_locale || default_locale
  found_locale && found_locale.to_sym
end

#next_article ⇒ Middleman::Sitemap::Resource

Deprecated.

Use #article_next instead.

The next (chronologically later) article after this one or nil if this is the most recent article.

Returns:

  • (Middleman::Sitemap::Resource) 


294
295
296
 
# File 'lib/middleman-blog/blog_article.rb', line 294

def next_article
  article_next()
end

#previous_article ⇒ BlogArticle

Deprecated.

Use #article_previous instead.

The previous (chronologically earlier) article before this one or nil if this is the first article.

Returns:



281
282
283
 
# File 'lib/middleman-blog/blog_article.rb', line 281

def previous_article
  article_previous()
end

#published? ⇒ Boolean

Whether or not this article has been published. An article is considered published in the following scenarios:

  1. Frontmatter does not set published to false and either

  2. The blog option publish_future_dated is true or

  3. The article’s date is after the current time

Returns:

  • (Boolean) 


92
93
94
 
# File 'lib/middleman-blog/blog_article.rb', line 92

def published?
  data['published'] != false && (blog_options.publish_future_dated || date <= Time.current)
end

#render(opts = {}, locs = {}, &block) ⇒ String

Render this resource to a string with the appropriate layout. Called automatically by Middleman.

Returns:

  • (String) 


52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
 
# File 'lib/middleman-blog/blog_article.rb', line 52

def render(opts={}, locs={}, &block)

  unless opts.has_key?( :layout )

    opts[:layout] = metadata[:options][:layout]
    opts[:layout] = blog_options.layout if opts[:layout].nil? || opts[:layout] == :_auto_layout

    # Convert to a string unless it's a boolean
    opts[:layout] = opts[:layout].to_s if opts[:layout].is_a? Symbol

  end

  content = super(opts, locs, &block)

  unless opts[:keep_separator]
    content.sub!(blog_options.summary_separator, '')
  end

  content
end

#slug ⇒ String

The “slug” of the article that shows up in its URL. The article slug is a parametrized version of the #title (lowercase, spaces replaced with dashes, etc) and can be used in the blog permalink as :title.

Returns:

  • (String) 


257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
 
# File 'lib/middleman-blog/blog_article.rb', line 257

def slug
  if data['slug']
    Blog::UriTemplates.safe_parameterize(data['slug'])

  elsif blog_data.source_template.variables.include?('title')
    Blog::UriTemplates.safe_parameterize(path_part('title'))

  elsif title
    Blog::UriTemplates.safe_parameterize(title)

  else
    raise "Can't generate a slug for #{path} because it has no :title in its path pattern or title/slug in its frontmatter."

  end
end

#summary(length = nil, ellipsis = '...') ⇒ String

The summary for this article, in HTML.

The blog option summary_generator can be set to a Proc in order to provide custom summary generation. The Proc is provided the rendered content of the article (without layout), the desired length to trim the summary to, and the ellipsis string to use. Otherwise the #default_summary_generator will be used, which returns either everything before the summary separator (set via the blog option summary_separator and defaulting to “READMORE”) if it is found, or the first summary_length characters of the post.

Parameters:

  • length (Number) (defaults to: nil) —

    How many characters to trim the summary to.

  • ellipsis (String) (defaults to: '...') —

    The ellipsis string to use when content is trimmed.

Returns:

  • (String) 


123
124
125
126
127
128
129
130
131
132
 
# File 'lib/middleman-blog/blog_article.rb', line 123

def summary(length=nil, ellipsis='...')
  rendered = render layout: false, keep_separator: true

  if blog_options.summary_generator
    blog_options.summary_generator.call(self, rendered, length, ellipsis)
  else
    default_summary_generator(rendered, length, ellipsis)
  end

end

#tags ⇒ Array<String>

A list of tags for this article, set from frontmatter.

Returns:

  • (Array<String>) —

    (never nil)



169
170
171
172
173
174
175
176
177
178
179
 
# File 'lib/middleman-blog/blog_article.rb', line 169

def tags

  article_tags = data['tags']

  if article_tags.is_a? String
    article_tags.split(',').map(&:strip)
  else
    Array(article_tags).map(&:to_s)
  end

end

#title ⇒ String

The title of the article, set from frontmatter.

Returns:

  • (String) 


78
79
80
 
# File 'lib/middleman-blog/blog_article.rb', line 78

def title
  data['title']
end