| Module | Pairwise |
| In: |
lib/pairwise.rb
|
Retrieve an item
Array of item id, text, added date, rank, wins, losses, added, ratings, skips.
| id: | the item ID |
# File lib/pairwise.rb, line 288
288: def get_item(id, rank_algorithm = nil)
289: path = "items/#{id}"
290: path += "?rank_algorithm=#{rank_algorithm}" if rank_algorithm
291: res = send_pairwise_request(path)
292: if res
293: [
294: id,
295: XML::Parser.content(res.body, 'item/data').first,
296: fetch_xml_attr('item', res, 'added').first,
297: fetch_xml_attr('item/questions/question', res, 'rank').first,
298: fetch_xml_attr('item/questions/question', res, 'wins').first,
299: fetch_xml_attr('item/questions/question', res, 'losses').first,
300: fetch_xml_attr('item/questions/question', res, 'score').first,
301: ]
302: end
303: end
Retrieve a prompt
Array of prompt id, question, array items for prompt
| id: | the prompt ID |
# File lib/pairwise.rb, line 310
310: def get_prompt(id)
311: res = send_pairwise_request("prompts/#{id}")
312: if res
313: [
314: id,
315: fetch_xml_attr('prompt/question', res).first,
316: fetch_xml_attr('prompt/items/item', res)
317: ]
318: end
319: end
Retrieve question
Array of question id, text, number of items, number of votes
| id: | the question ID |
# File lib/pairwise.rb, line 269
269: def get_question(id)
270: res = send_pairwise_request("questions/#{id}")
271: if res
272: [
273: id,
274: XML::Parser.content(res.body, 'question').first,
275: fetch_xml_attr('question', res, 'items').first,
276: fetch_xml_attr('question', res, 'votes').first,
277: fetch_xml_attr('question', res, 'active_and_inactive_items').first,
278: ]
279: end
280: end
Create an item for questions.
On success returns an array of item external IDs. Failure on passing non-existent question ID.
| data: | a single item data string or an array of item data strings. |
| question_ids: | an array of integers representing the external IDs of the questions the item is to be added to. |
| tracking: | data to store with the item. |
| active: | if exists it‘s are activate |
| voter_id: | if exists voter id is passed to pairwise. |
# File lib/pairwise.rb, line 70
70: def item(data, question_ids, tracking = nil, active = nil, voter_id = nil)
71: xml = xml_root("items")
72:
73: questions = question_ids.inject(XML::Node.new("questions")) do |doc, id|
74: question = XML::Node.new("question")
75: question["id"] = id.to_s
76: doc << question
77: end
78:
79: arrayed(data).each do |name|
80: xml.root << (XML::Node.new("item") << (XML::Node.new("data") << name) << questions.copy(true))
81: end
82: path = 'items/add' + query_string(['tracking', 'active', 'voter_id'].zip([tracking, active, voter_id]))
83: send_and_process(path, 'items/item', xml)
84: end
List items. Can pass a question and rank algorithm ID. List items for question according to rank algorithm.
Array each element being an item external ID followed by a rank value.
| question_id: | the question external ID of the question‘s items to |
restrict the list to or nil for all questions, default nil.
| rank_algorithm_id: | the rank algorithm to user in listing, default nil. |
| limit: | the number of items to return. |
# File lib/pairwise.rb, line 205
205: def list_items(question_id = nil, rank_algorithm_id = nil, data = nil, limit = nil)
206: path = "items/list/#{question_id.to_i}/#{rank_algorithm_id.to_i}"
207: path += "/#{limit}" unless limit.nil?
208: path += "?data=1" unless data.nil?
209: res = send_pairwise_request(path)
210: if res
211: [
212: fetch_xml_attr('items/item', res),
213: XML::Parser.content(res.body, 'items/item'),
214: fetch_xml_attr('items/item', res, 'active'),
215: fetch_xml_attr('items/item', res, 'rank'),
216: fetch_xml_attr('items/item', res, 'wins'),
217: fetch_xml_attr('items/item', res, 'losses'),
218: fetch_xml_attr('items/item', res, 'added'),
219: fetch_xml_attr('items/item', res, 'ratings'),
220: fetch_xml_attr('items/item', res, 'skips'),
221: fetch_xml_attr('items/item', res, 'score'),
222: ].transpose
223: end
224: end
List questions.
Array each element is a question as [id, text].
# File lib/pairwise.rb, line 229
229: def list_questions
230: res = send_pairwise_request("questions/list")
231: if res
232: fetch_xml_attr('questions/question', res).zip(XML::Parser.content(res.body, 'questions/question'))
233: end
234: end
List votes. Can pass a question ID and optional item IDs. List vote for question and item.
Array each element being a vote external ID followed by prompt ID, voter ID, and array of IDs of items that were voted for.
| question_id: | the question external ID of the question‘s items to |
restrict the list to or nil for all questions, default nil.
| item_id: | restrict votes to this item ID, default nil. |
| limit: | limit to retrieve this many votes |
# File lib/pairwise.rb, line 246
246: def list_votes(question_id = nil, item_id = nil, limit = nil)
247: path = "votes/list"
248: path += "/#{question_id}" if question_id
249: path += "/#{item_id}" if item_id
250: path += "?limit=#{limit}" if limit
251: res = send_pairwise_request(path)
252: if res
253: [
254: fetch_xml_attr('votes/vote', res),
255: fetch_xml_attr('votes/vote/prompt', res, 'id'),
256: fetch_xml_attr('votes/vote/voter', res, 'id'),
257: fetch_xml_attr('votes/vote', res, 'tracking'),
258: fetch_xml_attr('votes/vote', res, 'response_time'),
259: XML::Parser.parse_with_nils(res.body, 'votes/vote/items', 'item')
260: ].transpose
261: end
262: end
Create n prompts for question and voter. Can restrict to items and specify number of items expected in returned prompt.
Array with each member a prompt external id followed by an array of item external IDs for that prompt. If data is passed the external ids are followed by an array of item data.
| question_id: | the question to create the prompt for. |
| voter_id: | the voter to create the prompt for. A value of 0 is the anonymous voter. |
| n: | the number of prompts to create, default 1. |
| item_ids: | an array of items external ids to limit the items in the created prompt to, default nil. |
| num_items: | the number of items per prompt, default 2. |
| data: | retrieve data as well |
# File lib/pairwise.rb, line 146
146: def prompt(question_id, voter_id, n = 1, prime = false, num_items = 2, data = nil)
147: res = "prompts/create/#{question_id}/#{voter_id || 0}/#{n}"
148: res += "/1" if prime
149: res += "?data=1" unless data.nil?
150: res = send_pairwise_request(res, nil, 'Get')
151:
152: # process response
153: if res
154: prompt_ids = fetch_xml_attr('prompts/prompt', res)
155: item_ids = fetch_xml_attr('prompts/prompt/items/item', res)
156: ret = [prompt_ids, prompt_ids.map { |id| item_ids.slice!(0, num_items) }]
157: if data
158: item_content = XML::Parser.content(res.body, 'prompts/prompt/items/item')
159: ret << prompt_ids.map { |id| item_content.slice!(0, num_items) }
160: end
161: ret
162: end
163: end
Create a question.
Array of question external IDs.
| data: | a single question string or an array of question strings. |
# File lib/pairwise.rb, line 50
50: def question(data)
51: xml = xml_root("questions")
52:
53: arrayed(data).each do |name|
54: xml.root << (XML::Node.new("question") << name)
55: end
56:
57: send_and_process('questions/add', 'questions/question', xml)
58: end
Set the pairwise server auth, host, and protocol values.
| options:host: | the pairwise server. |
| options:user: | the pairwise user. |
| options:password: | the pairwise password for user. |
| options:protocol: | the internet protocol to use, probably HTTP or HTTPS. |
# File lib/pairwise.rb, line 22
22: def server(options)
23: @auth = Base64.encode64("#{options[:user]}:#{options[:pass]}")
24: @host = options[:host]
25: @protocol = options[:protocol]
26: @key = options[:key] && Base64.encode64(options[:key])
27: end
Update an item‘s state.
On response returns true. Failure on incorrect item id.
| item_id: | the external ID of the items whose state to set. |
| state: | state will be set to ‘activated’ if state is true. Otherwise |
state will be set to ‘suspended’.
# File lib/pairwise.rb, line 93
93: def update_item_state(item_id, state)
94: !send_pairwise_request("items/#{item_id}/#{state ? 'activate' : 'suspend'}", nil, 'Get').nil?
95: end
Update the state of voter feature name to value.
On success returns voter external ID.
| voter_id: | the external voter ID. |
| name: | the feature to set. |
| value: | the value to set the feature to. |
# File lib/pairwise.rb, line 126
126: def update_voter_state(voter_id, name, value)
127: send_and_process("voters/set/#{voter_id}?#{name}=#{value}", 'voter')
128: end
Create a user
Added user login.
| login: | login of user |
| email: | email of user |
| password: | password of user |
# File lib/pairwise.rb, line 36
36: def user(login, email, password)
37: xml = xml_root("user")
38: xml.root << (XML::Node.new("login") << login)
39: xml.root << (XML::Node.new("email") << email)
40: xml.root << (XML::Node.new("password") << Base64.encode64(password))
41:
42: send_and_process("users/add?key=#{key}", 'user', xml)
43: end
Create a vote on a prompt for an item or a skip if nil. Can be cast for a voter or the anonymous voter and a response time can be sent.
Array of vote external IDs.
| prompt_id: | the prompt external id to record a vote for. |
| item_id: | the item_id to record the vote for. If item_id is nil or false |
a skip vote is sent.
| voter_id: | the voter external ID to record the vote for. Defaults to the |
anonymous voter, a value of 0.
| response_time: | the response time of the vote, default 0. |
| tracking: | additional data to store with pairwise. |
# File lib/pairwise.rb, line 189
189: def vote(prompt_id, item_id = nil, voter_id = 0, response_time = 0, tracking = nil)
190: path = "votes/add/#{prompt_id}/#{voter_id || 0}/#{response_time}"
191: path += "/#{item_id}" if item_id
192: path += "?tracking=#{tracking}" if tracking
193: send_and_process(path, 'vote')
194: end
Create voters with given features. Each can pass a single hash of features to create a single voter or an array of hashes to create multiple voters.
On sucess returns the voter external ID.
| features: | a hash of name to value pairs for the voter‘s features. |
# File lib/pairwise.rb, line 103
103: def voter(features = {})
104: xml = arrayed(features).inject(xml_root("voters").root) do |voters, hash|
105: voter = XML::Node.new("voter")
106: features = XML::Node.new("features")
107: hash.each do |name, value|
108: feature = XML::Node.new("feature") << value
109: feature["name"] = name.to_s
110: features << feature
111: end
112: voters << (voter << features)
113: end
114: send_and_process('voters/add', 'voters/voter', xml)
115: end
wrap in an array if not an array.
| object: | object or array. |
# File lib/pairwise.rb, line 365
365: def arrayed(object) # :doc:
366: (object.is_a?(Array) ? object : [object])
367: end
| xml: | an HTTP response. |
| path: | the path to search in xml. |
| attribute: | the attribute to return for each element in the search path. |
# File lib/pairwise.rb, line 358
358: def fetch_xml_attr(path, xml, attribute = "id") # :doc:
359: XML::Parser.parse(xml.body, "/pairwise/#{path}", attribute)
360: end
Response from the pairwise path parsed with the res_path.
| path: | where to send the pairwise request to. |
| res_path: | the parse path for the xml. |
| xml: | the data to send to pairwise, default nil. |
# File lib/pairwise.rb, line 328
328: def send_and_process(path, res_path, xml = nil) # :doc:
329: # send XML
330: res = send_pairwise_request(path, xml)
331: # process response
332: fetch_xml_attr(res_path, res) if res
333: end
| path: | where to send the pairwise request to. |
| xml: | the post body to send. If xml is nil and method is nil (see below) |
a get request is sent. Default nil.
| method: | type of request to send. If method is nil request type is |
determined by the value of value of xml.
# File lib/pairwise.rb, line 341
341: def send_pairwise_request(path, xml = nil, method = nil) # :doc:
342: url = URI.parse("#{protocol}://#{host}/#{path}")
343: headers = {
344: 'Content-Type' => 'text/xml',
345: 'Authorization' => "Basic #{auth}"
346: }
347: res = Net::HTTP.new(url.host, url.port)
348: res.use_ssl = true if url.port == Net::HTTP.https_default_port
349: # if xml is nil assum GET, otherwise POST
350: res = res.request(('Net::HTTP::' + (method || (xml.nil? ? 'Get' : 'Post'))).constantize.new(url.request_uri, headers), xml && xml.to_s)
351: res.is_a?(Net::HTTPSuccess) ? res : nil
352: end