Module: Nitro::FeedHelper

Includes:
Markup
Defined in:
lib/nitro/helper/feed.rb

Overview

A helper that provides Feed related methods.

To include this helper into your controller, add the following at the beginning of your controller:

helper :feed

Then define actions that set an appropriate content_type and use build_(rss|atom|opml) to generate your desired feed. See below for details.

RSS 0.91, 1.0 and 2.0

response.content_type = "application/rss+xml"
build_rss(og_objects, 
  :version => "0.9", 
  :base => context.host_url, # + object.to_href results in an item-link
  :link => context.host_url+"/feed", # link to this feed
  :title => "Feed Title", 
  :description => "What this feed is about", 
  :search_title => "Search Form Here",
  :search_description => "Search description",
  :search_input_name => "search_field",
  :search_form_action => "http://url/to/search_action"
)

For RSS 1.0 or RSS 2.0 just change :version (defaults to ‘0.91’), possible :version options are “0.9”, “0.91”, “1.0” and “2.0”

  • for RSS 0.9 :language is required (or defaults to ‘en’)

  • for all RSS versions :title, :link and/or :base, :description are required

individual objects have to respond to at least:

  • 1.0/0.9/2.0 require @title

  • 1.0/0.9 require @to_href

  • 2.0 requires @body

if it doesn’t, no item is created

  • @update_time, @create_time or @date is used for item.date

  • so if Og’s “is Timestamped” is being used, it’ll be @update_time

  • @author.name can optionally be used for item.author

Atom 1.0

response.content_type = "application/atom+xml"
build_atom(og_objects,
  :title => "Feed Title",
  :base => context.host_url, # + object.to_href results in an item-link
  :link => context.host_url+"/atomfeed",
  :id => "your_unique_id",  # :base is being used unless :id specified (:base is recommended)
  :author_name => "Takeo",
  :author_email => "[email protected]",
  :author_link => "http://uri.to/authors/home",
)

individual objects have to respond to at least:

  • @title

  • @to_href

  • @update_time/@create_time/@date (at least one of them)

if it doesn’t, no entry is created

optional:

  • @body (taken as summary (256 chars))

  • @full_content

  • use Og’s “is Timestamped”, so both @update_time and @create_time can be used

  • @author.name

  • @author.link

  • @author.email # be careful, you don’t want to publish your users email address to spammers

OPML 1.0 feed lists

Fabian: Eew, who invented OPML? Who needs it? Implementing it in a very rough way anyway though. takes a Hash of Feeds and optional options

response.content_type = "application/opml+xml"
build_opml(
  {
  "http://oxyliquit.de/feed" => "rss",
  "http://oxyliquit.de/feed/questions" => "rss",
  "http://oxyliquit.de/feed/tips" => "rss",
  "http://oxyliquit.de/feed/tutorials" => "rss"
  },
  :title => "My feeds"
)

Instance Method Summary collapse

Instance Method Details

#build_atom(objects, options = {}) ⇒ Object Also known as: atom

Atom 1.0 feeds.



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
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
 
# File 'lib/nitro/helper/feed.rb', line 201

def build_atom(objects, options = {})
  
  # default options
  options = {
    :title => 'Syndication',
  }.update(options)
  
  raise "first param must be a collection of objects!" unless objects.respond_to?(:to_ary)
  raise "your object(s) have to respond to :update_time, :create_time or :date" unless objects[0].respond_to?(:update_time) or objects[0].respond_to?(:create_time) or objects[0].respond_to?(:date)
  raise "Option ':base' cannot be omitted!" unless options[:base]
  
  # new XML Document for Atom
  atom = REXML::Document.new
  atom << REXML::XMLDecl.new("1.0", "utf-8")
  
    # Root element <feed />
    feed = REXML::Element.new("feed").add_namespace("http://www.w3.org/2005/Atom")
    
      # Required feed elements
      
      # id: Identifies the feed using a universally unique and permanent URI.
      iduri = URI.parse(options[:id] || options[:base]).normalize.to_s
      id = REXML::Element.new("id").add_text(iduri)
      feed << id
      
      # title: Contains a human readable title for the feed.
      title = REXML::Element.new("title").add_text(options[:title])
      feed << title
      
      # updated: Indicates the last time the feed was modified in a significant way. 
      latest = Time.at(0) # a while back
      objects.each do |o|
        if o.respond_to?(:update_time)
          latest = o.update_time if o.update_time > latest
        elsif o.respond_to?(:create_time)
          latest = o.create_time if o.create_time > latest
        elsif o.respond_to?(:date)
          latest = o.date if o.date > latest
        end
      end
      updated = REXML::Element.new("updated").add_text(latest.iso8601)
      feed << updated
      
      # Recommended feed elements
      
      # link: A feed should contain a link back to the feed itself.
      if options[:link]
        link = REXML::Element.new("link")
        link.add_attributes({ "rel" => "self", "href" => options[:link] })
        feed << link
      end
      
      # author: Names one author of the feed.
      if options[:author_name]  # name is required for author
        author = REXML::Element.new("author")
        author_name = REXML::Element.new("name").add_text(options[:author_name])
        author << author_name
        if options[:author_email]
          author_email = REXML::Element.new("email").add_text(options[:author_email])
          author << author_email
        end
        if options[:author_link]
          author_link = REXML::Element.new("uri").add_text(options[:author_link])
          author << author_link
        end
        feed << author
      end
      
      # Optional feed elements
      
      # category:
      # contributor:
      # generator: Identifies the software used to generate the feed.
      generator = REXML::Element.new("generator")
      generator.add_attributes({ "uri" => "http://www.nitroproject.org", "version" => Nitro::Version })
      generator.add_text("Nitro")
      feed << generator
      # icon
      # logo
      # rights
      # subtitle
                
      # Entries
      objects.each do |o|
        
        # new Entry (called "item" in RSS)
        unless o.respond_to?(:to_href) and o.respond_to?(:title) 
          next
        end
        entry = REXML::Element.new("entry")
      
        # Required entry elements
        
          # id
          if o.respond_to?(:to_href)
            id = REXML::Element.new("id").add_text("#{options[:base]}#{fhref o}")
            entry << id
          end
          
          # title
          if o.respond_to?(:title)
            title = REXML::Element.new("title").add_text(o.title)
            entry << title
          end
          
          # updated
          updated = Time.at(0) # a while back
          if o.respond_to?(:update_time)
            updated = o.update_time
          elsif o.respond_to?(:create_time)
            updated = o.create_time
          elsif o.respond_to?(:date)
            updated = o.date
          end
          entry << REXML::Element.new("updated").add_text(updated.iso8601)
          
        # Recommended entry elements
        
          # author
          if o.respond_to?(:author)
            
            if o.author.kind_of?(Hash)
              oauthor = OpenStruct.new(o.author)
            else
              oauthor = o.author
            end
            
            author = REXML::Element.new("author")
            author_name = REXML::Element.new("name").add_text(oauthor.name)
            author << author_name
            if oauthor.email
              author_email = REXML::Element.new("email").add_text(oauthor.email)
              author << author_email
            end
            if oauthor.link
              author_link = REXML::Element.new("uri").add_text(oauthor.link)
              author << author_link
            end
            entry << author
          end
          
          # summary
          
          if o.respond_to?(:body)
            summary = REXML::Element.new("summary")
            #TODO: think about whether 256 chars should be a fixed limit
            summary.add_text(o.body.first_char(256).gsub(/<[^>]+>/, ' '))
            entry << summary
          end
          
          # content
          # may have the type text, html or xhtml
          
          if o.respond_to?(:full_content)
            content = REXML::Element.new("content")
            #TODO: think about whether markup should always be done
            content.add_text(markup(o.full_content))
            entry << content
          end
          
          # link: An entry must contain an alternate link if there is no content element.
          
          if o.respond_to?(:to_href)
            link = REXML::Element.new("link")
            link.add_attributes({ "rel" => "alternate", "href" => "#{options[:base]}#{fhref o}" })
            entry << link
          end
          
          # Optional entry elements
        
          # category
          # could be used for Tags maybe?
          # contributor
          # published

          if o.respond_to?(:create_time)
            published = REXML::Element.new("published")
            published.add_text(o.create_time.iso8601)
            entry << published
          end

          # source
          # rights
        
        # don't forget to add the entry to the feed
        feed << entry
        
      end if objects.size > 0 # objects/entries
      
  atom << feed
  
  return atom.to_s
end

#build_opml(feedhash, options = {}) ⇒ Object Also known as: opml

OPML 1.0 feed lists Fabian: eww, who invented OPML? Who needs it? Implementing it in a very rough way anyway though. Takes a Hash of Feeds and optional options.



401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
 
# File 'lib/nitro/helper/feed.rb', line 401

def build_opml(feedhash, options = {})
  
  # new XML Document for OPML
  opml = REXML::Document.new
  opml << REXML::XMLDecl.new("1.0", "utf-8")
  
  # Root element <opml />
  opml = REXML::Element.new("opml")
  opml.add_attribute("version", "1.0")

  # head
  head = REXML::Element.new("head")
    # title
    if options[:title]
      title = REXML::Element.new("title").add_text(options[:title])
      head << title
    end
    # dateCreated
    # dateModified
    # ownerName
    # ownerEmail 
  opml << head
  
  # body
  body = REXML::Element.new("body")
    feedhash.each do |url, type|
      outline = REXML::Element.new("outline")
      outline.add_attributes({ "type" => type, "xmlUrl" => url })
      body << outline
    end
  opml << body
  
  return opml.to_s
end

#build_rss(objects, options = {}) ⇒ Object Also known as: rss

RSS 0.91, 1.0, 2.0 feeds.



106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
 
# File 'lib/nitro/helper/feed.rb', line 106

def build_rss(objects, options = {})

  # default options
  options = {
    :title => 'Syndication',
    :description => 'Syndication',
    :version => '0.9',
    :language => 'en',  # required by 0.9
  }.update(options)

  raise "Option ':version' contains a wrong version!" unless %w(0.9 0.91 1.0 2.0).include?(options[:version])

  options[:base] ||= options[:link]
  raise "Option ':base' cannot be omitted!" unless options[:base]
  
  # build rss
  rss = RSS::Maker.make(options[:version]) do |maker|
    maker.channel.title = options[:title]
    maker.channel.description = options[:description]
    if options[:link]
      maker.channel.link = options[:link]
    else
      maker.channel.link = options[:base] #FIXME: not sure
    end 
    case options[:version]
      when '0.9', '0.91'
        maker.channel.language = options[:language]
      when '1.0'
        if options[:link]
          maker.channel.about = options[:link]
        else
          raise "Option ':link' is required for RSS 1.0"
        end
    end
    maker.channel.generator = "Nitro #{Nitro::Version}"

    maker.items.do_sort = true

    # items for each object
    # * 1.0/0.9/2.0 require @title
    # * 1.0/0.9 require @link
    # * 2.0 requires @description
    objects.each do |o|
      
      # new Item
      item = maker.items.new_item
      
      # Link
      item.link = "#{options[:base]}#{fhref o}" if o.respond_to?(:to_href)
      item.guid.content = "#{options[:base]}#{fhref o}" if options[:version] == '2.0' && o.respond_to?(:to_href)
      
      # Title
      item.title = o.title if o.respond_to?(:title)
      
      # Description
      if o.respond_to? :body and body = o.body
        #TODO: think about whether markup should always be done 
        # and whether 256 chars should be a fixed limit
        #item.description = markup(body.first_char(256)) 
        # markup disabled, feedvalidator.org says "description should not contain HTML"
        # so removing everything that looks like a tag
        item.description = body.first_char(256).gsub!(/<[^>]+>/, ' ')
      end
      
      # Date  (item.date asks for a Time object, so don't .to_s !)
      if o.respond_to?(:update_time)
        item.date = o.update_time
      elsif o.respond_to?(:create_time)
        item.date = o.create_time
      elsif o.respond_to?(:date)
        item.date = o.date
      end
      
      # Author. Use .to_s to be more flexible.
      
      if o.respond_to?(:author)
        item.author = o.author.to_s
      end
      
    end if objects.size > 0 # objects/items

    # search form
    maker.textinput.title = options[:search_title] if options[:search_title]
    maker.textinput.description = options[:search_description] if options[:search_description]
    maker.textinput.name = options[:search_input_name] if options[:search_input_name]
    maker.textinput.link = options[:search_form_action] if options[:search_form_action]
  end
  
  return rss.to_s
end

#fhref(obj) ⇒ Object

Helper



440
441
442
 
# File 'lib/nitro/helper/feed.rb', line 440

def fhref(obj)
  "/#{obj.to_href}".squeeze('/')
end