Class: Forem::Survey

Inherits:
APIResource show all
Extended by:
APIOperations::List, APIOperations::Retrieve
Defined in:
lib/forem/resources/survey.rb

Overview

Represents a survey published on a Forem instance.

Surveys are structured questionnaires that can be presented to community members. They can be listed or retrieved individually. Survey responses are exposed through two endpoints — #poll_votes for multiple-choice poll selections and #poll_text_responses for free-text answers.

The /api/surveys/{id}/responses endpoint that earlier versions of this gem hit no longer exists in the Forem API; it was replaced by those two cursor-paginated endpoints.

Available operations (via mixins):

- +List+     — GET /api/surveys
- +Retrieve+ — GET /api/surveys/:id_or_slug (getSurveyByIdOrSlug)

Survey Fields

  • id (Integer)
  • title (String)
  • slug (String)
  • survey_type_of (String) — Survey category
  • active (Boolean) — Whether the survey is currently active

Authentication

All survey endpoints require an admin API key.

Examples:

List active surveys

surveys = client.surveys.list(active: true)
surveys.each { |s| puts s.title }

Retrieve a specific survey by id or slug

survey = client.surveys.retrieve(3)
survey = client.surveys.retrieve("my-survey-slug")

Iterate every poll vote across all pages

survey = client.surveys.retrieve(3)
survey.poll_votes.auto_paging_each { |v| puts v.poll_option_id }

See Also:

Constant Summary collapse

OBJECT_NAME = 
"survey"
RESOURCE_PATH = 
"/api/surveys"

Instance Attribute Summary

Attributes inherited from ForemObject

#requestor

Instance Method Summary collapse

Methods included from APIOperations::List

list

Methods included from APIOperations::Retrieve

retrieve

Methods inherited from APIResource

#refresh, resource_path, #resource_url

Methods inherited from ForemObject

#==, #[], #[]=, construct_from, cursor_list, #initialize, #inspect, #method_missing, paginated_list, #respond_to_missing?, #to_hash

Methods included from APIOperations::Request

included, #request

Constructor Details

This class inherits a constructor from Forem::ForemObject

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class Forem::ForemObject

Instance Method Details

#poll_text_responses(params = {}, opts = {}) ⇒ Forem::ListObject<Forem::ForemObject>

Return the free-text answers recorded for this survey.

Sends a GET request to /api/surveys/:id_or_slug/poll_text_responses. Cursor-paginated by :after on the last seen response id; see #poll_votes for paging details.

Examples:

survey = client.surveys.retrieve(3)
survey.poll_text_responses.each { |r| puts r.text_content }

Parameters:

  • params (Hash) (defaults to: {}) —

    query parameters

  • opts (Hash) (defaults to: {}) —

    per-request options

Options Hash (params):

  • :after (Integer) —

    return only responses with id strictly greater than this value (cursor)

  • :per_page (Integer) —

    page size (default 30)

Returns:

See Also:



90
91
92
93
94
 
# File 'lib/forem/resources/survey.rb', line 90

def poll_text_responses(params = {}, opts = {})
  opts = opts.dup
  opts[:requestor] ||= @requestor
  Forem::ForemObject.cursor_list("#{resource_url}/poll_text_responses", params, opts)
end

#poll_votes(params = {}, opts = {}) ⇒ Forem::ListObject<Forem::ForemObject>

Return the multiple-choice poll selections recorded for this survey.

Sends a GET request to /api/surveys/:id_or_slug/poll_votes. Pagination is cursor-based — pass the last seen vote id as :after (or use ListObject#auto_paging_each, which threads the cursor automatically).

Examples:

survey = client.surveys.retrieve(3)
survey.poll_votes.auto_paging_each { |v| puts v.id }

Parameters:

  • params (Hash) (defaults to: {}) —

    query parameters

  • opts (Hash) (defaults to: {}) —

    per-request options

Options Hash (params):

  • :after (Integer) —

    return only votes with id strictly greater than this value (cursor)

  • :per_page (Integer) —

    page size (default 30)

Returns:

See Also:



67
68
69
70
71
 
# File 'lib/forem/resources/survey.rb', line 67

def poll_votes(params = {}, opts = {})
  opts = opts.dup
  opts[:requestor] ||= @requestor
  Forem::ForemObject.cursor_list("#{resource_url}/poll_votes", params, opts)
end