Rename events_order to events_list_order and readd events_order

`events_order` determines how to select events for outputting, whereas
`events_list_order` determines how to list selected events in the
output.

app/models/agents/data_output_agent.rb

@@ -45,9 +45,14 @@ class DataOutputAgent < Agent
               "_contents": "tag contents (can be an object for nesting)"
             }
 
-        # Ordering events in the output
+        # Ordering events
 
-        #{description_events_order('events in the output')}
+        #{description_events_order('events')}
+
+        DataOutputAgent will select the last `events_to_show` entries of its received events sorted in the order specified by `events_order`, which is defaulted to the event creation time.
+        So, if you have multiple source agents that may create many events in a run, you may want to either increase `events_to_show` to have a larger "window", or specify the `events_order` option to an appropriate value (like `date_published`) so events from various sources are properly mixed in the resulted feed.
+
+        There is also an option `events_list_order` to control the order of events listed in the output, with the same format as `events_order`.  It is defaulted to `#{Utils.jsonify(DEFAULT_EVENTS_ORDER['events_list_order'])}` so the latest entry is listed first.
 
         # Liquid Templating
 
@@ -175,7 +180,16 @@ def push_hubs
       interpolated['push_hubs'].presence || []
     end
 
-    def sorted_events(reload = false)
+    DEFAULT_EVENTS_ORDER = {
+      'events_order' => nil,
+      'events_list_order' => [["{{_index_}}", "number", true]],
+    }
+
+    def events_order(key = SortableEvents::EVENTS_ORDER_KEY)
+      super || DEFAULT_EVENTS_ORDER[key]
+    end
+
+    def latest_events(reload = false)
       events =
         if (event_ids = memory[:event_ids]) &&
            memory[:events_order] == events_order &&
@@ -229,7 +243,7 @@ def receive_web_request(params, method, format)
         end
       end
 
-      source_events = sorted_events()
+      source_events = sort_events(latest_events(), 'events_list_order')
 
       interpolation_context.stack do
         interpolation_context['events'] = source_events
@@ -297,7 +311,7 @@ def receive(incoming_events)
       url = feed_url(secret: interpolated['secrets'].first, format: :xml)
 
       # Reload new events and update cache
-      sorted_events(true)
+      latest_events(true)
 
       push_hubs.each do |hub|
         push_to_hub(hub, url)

db/migrate/20160607055850_change_events_order_to_events_list_order.rb

@@ -0,0 +1,25 @@
+class ChangeEventsOrderToEventsListOrder < ActiveRecord::Migration
+  def up
+    Agents::DataOutputAgent.find_each do |agent|
+      if value = agent.options.delete('events_order')
+        agent.options['events_list_order'] = value
+        agent.save!(validate: false)
+      end
+    end
+  end
+
+  def down
+    Agents::DataOutputAgent.transaction do
+      Agents::DataOutputAgent.find_each do |agent|
+        if agent.options['events_order']
+          raise ActiveRecord::IrreversibleMigration, "Cannot revert migration because events_order is configured"
+        end
+
+        if value = agent.options.delete('events_list_order')
+          agent.options['events_order'] = value
+          agent.save!(validate: false)
+        end
+      end
+    end
+  end
+end

spec/models/agents/data_output_agent_spec.rb

@@ -142,7 +142,7 @@
           "url" => "http://imgs.xkcd.com/comics/evolving0.png",
           "title" => "Evolving yet again with a past date",
           "date" => '2014/05/05',
-          "hovertext" => "Something else"
+          "hovertext" => "A small text"
         }
       end
 
@@ -166,7 +166,7 @@
 
            <item>
             <title>Evolving yet again with a past date</title>
-            <description>Secret hovertext: Something else</description>
+            <description>Secret hovertext: A small text</description>
             <link>http://imgs.xkcd.com/comics/evolving0.png</link>
             <pubDate>#{Time.zone.parse(event3.payload['date']).rfc2822}</pubDate>
             <guid isPermaLink="false">#{event3.id}</guid>
@@ -216,7 +216,7 @@
           'items' => [
             {
               'title' => 'Evolving yet again with a past date',
-              'description' => 'Secret hovertext: Something else',
+              'description' => 'Secret hovertext: A small text',
               'link' => 'http://imgs.xkcd.com/comics/evolving0.png',
               'guid' => {"contents" => event3.id, "isPermaLink" => "false"},
               'pubDate' => Time.zone.parse(event3.payload['date']).rfc2822,
@@ -244,20 +244,20 @@
 
       describe 'ordering' do
         before do
-          agent.options['events_order'] = ['{{title}}']
+          agent.options['events_order'] = ['{{hovertext}}']
+          agent.options['events_list_order'] = ['{{title}}']
         end
 
         it 'can reorder the events_to_show last events based on a Liquid expression' do
-          # Check that ordering takes place before limiting, not after
           agent.options['events_to_show'] = 2
           asc_content, _status, _content_type = agent.receive_web_request({ 'secret' => 'secret2' }, 'get', 'application/json')
-          expect(asc_content['items'].map {|i| i["title"] }).to eq(["Evolving again", "Evolving yet again with a past date"])
+          expect(asc_content['items'].map {|i| i["title"] }).to eq(["Evolving", "Evolving again"])
 
           agent.options['events_to_show'] = 40
           asc_content, _status, _content_type = agent.receive_web_request({ 'secret' => 'secret2' }, 'get', 'application/json')
           expect(asc_content['items'].map {|i| i["title"] }).to eq(["Evolving", "Evolving again", "Evolving yet again with a past date"])
 
-          agent.options['events_order'] = [['{{title}}', 'string', true]]
+          agent.options['events_list_order'] = [['{{title}}', 'string', true]]
 
           desc_content, _status, _content_type = agent.receive_web_request({ 'secret' => 'secret2' }, 'get', 'application/json')
           expect(desc_content['items']).to eq(asc_content['items'].reverse)