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) 


317
318
319
 
# File 'lib/middleman-blog/blog_article.rb', line 317

def article_locale_next
  blog_data.local_articles.reverse.find { |a| a.date > 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:



307
308
309
 
# File 'lib/middleman-blog/blog_article.rb', line 307

def article_locale_previous
  blog_data.local_articles.find { |a| a.date < 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) 


297
298
299
 
# File 'lib/middleman-blog/blog_article.rb', line 297

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

#article_previous ⇒ BlogArticle

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

Returns:



287
288
289
 
# File 'lib/middleman-blog/blog_article.rb', line 287

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

#blog_data ⇒ BlogData

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

Returns:



28
29
30
 
# File 'lib/middleman-blog/blog_article.rb', line 28

def blog_data
  blog_controller.data
end

#blog_options ⇒ ConfigurationManager

The options for this article’s blog.

Returns:

  • (ConfigurationManager) 


37
38
39
 
# File 'lib/middleman-blog/blog_article.rb', line 37

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) 


95
96
97
 
# File 'lib/middleman-blog/blog_article.rb', line 95

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) 


199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
 
# File 'lib/middleman-blog/blog_article.rb', line 199

def date
  return @_date if @_date

  frontmatter_date = data['date']

  # First get the date from frontmatter
  @_date = if frontmatter_date.is_a? Time
    frontmatter_date.in_time_zone
  else
    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.



135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
 
# File 'lib/middleman-blog/blog_article.rb', line 135

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&.positive?
    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)



177
178
179
180
181
182
183
184
185
186
187
 
# File 'lib/middleman-blog/blog_article.rb', line 177

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

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

  default_locale = I18n.default_locale if defined? ::I18n

  found_locale = frontmatter_locale || filename_locale || default_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) 


276
277
278
 
# File 'lib/middleman-blog/blog_article.rb', line 276

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:



263
264
265
 
# File 'lib/middleman-blog/blog_article.rb', line 263

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) 


84
85
86
 
# File 'lib/middleman-blog/blog_article.rb', line 84

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) 


47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
 
# File 'lib/middleman-blog/blog_article.rb', line 47

def render(opts = {}, locs = {}, &block)
  unless opts.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)

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

  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) 


239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
 
# File 'lib/middleman-blog/blog_article.rb', line 239

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) 


115
116
117
118
119
120
121
122
123
 
# File 'lib/middleman-blog/blog_article.rb', line 115

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)



158
159
160
161
162
163
164
165
166
 
# File 'lib/middleman-blog/blog_article.rb', line 158

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) 


70
71
72
 
# File 'lib/middleman-blog/blog_article.rb', line 70

def title
  data['title'].to_s
end