Class: Forem::Event

Inherits:
APIResource show all
Extended by:
APIOperations::Create, APIOperations::List, APIOperations::Retrieve, APIOperations::Update
Includes:
APIOperations::Delete, APIOperations::Save
Defined in:
lib/forem/resources/event.rb

Overview

Represents an event on a Forem instance.

Events can represent live streams, hackathons, takeovers, or community meetups. The API supports full CRUD operations, and the create endpoint behaves as an idempotent upsert when matching slugs or numeric IDs are provided.

Available operations (via mixins):

- +List+     — GET /api/events (supports +type_of+ filtering)
- +Create+   — POST /api/events (idempotent upsert, admin privileges)
- +Retrieve+ — GET /api/events/:id_or_slug
- +Update+   — PUT /api/events/:id_or_slug (admin privileges)
- +Delete+   — class- and instance-level delete (DELETE /api/events/:id_or_slug, admin privileges)
- +Save+     — instance-level save (create or update)

List Parameters

When calling Event.list, the following query parameters are supported:

  • type_of (String) — Filter by event type: "live_stream", "takeover", "other", "challenge"
  • page (Integer) — Page number (default: 1)
  • per_page (Integer) — Items per page (default: 30, max: 1000)

Event Fields

  • id (Integer) — Assigned by the API
  • title (String, required) — Title of the event
  • event_name_slug (String, required) — Lowercase slug identifier (e.g. "hackrice")
  • event_variation_slug (String, required) — Edition/season/year slug (e.g. "13" or "2026")
  • description (String) — Markdown or plain text description
  • full_details (String) — Comprehensive plain text / Markdown dump of all event details, agenda, and context notes
  • start_time (String / ISO 8601, required) — Start timestamp
  • end_time (String / ISO 8601, required) — End timestamp
  • type_of (String) — One of: "live_stream", "takeover", "other", "challenge"
  • broadcast_config (String) — One of: "no_broadcast", "tagged_broadcast", "global_broadcast"
  • primary_stream_url (String) — Video streaming URL (YouTube, Twitch, Streamyard)
  • manual_broadcast_end (Boolean) — Whether broadcasting end is manually handled
  • published (Boolean) — Whether the event is publicly listed
  • elevated (Boolean) — Whether the event is featured/elevated
  • bg_color_hex (String) — 6-digit hex background color code (e.g. "#7C3AED")
  • cover_image (String) — Uploaded cover image filename
  • remote_cover_image_url (String) — Remote URL to fetch, crop, and store as cover image
  • remove_cover_image (Boolean) — Flag to delete the existing cover image
  • tag_list (String) — Comma-separated list of tags
  • user_id (Integer) — ID of the host/creator user
  • organization_id (Integer) — ID of the host organization
  • page_id (Integer) — ID of an associated page
  • delegate_to_page (Boolean) — Whether landing page links delegate directly to page
  • data (Hash) — Structured metadata such as location, format, external_registration_url
  • cover_image_url (String) — Public URL to the uploaded cover image
  • social_image_url (String) — Public URL to the 1200x630 social card crop or default fallback
  • background_hex_color (String) — Effective background hex color
  • formatted_date_range (String) — Display-ready date range string (e.g. "AUG 28 - 30")
  • location (String) — Display location string (e.g. "Everywhere, Worldwide")
  • format (String) — Display format pill label (e.g. "DIGITAL", "IN-PERSON")

Examples:

List published events or filter by type_of

events = client.events.list(type_of: "challenge")
events.each { |e| puts "#{e.title} (#{e.formatted_date_range})" }

Retrieve an event by numeric ID or slug

event = client.events.retrieve(12)
puts event.title

Create or upsert an event

event = client.events.create(
  title: "HackRice XIII",
  event_name_slug: "hackrice",
  event_variation_slug: "13",
  start_time: "2026-09-11T10:00:00Z",
  end_time: "2026-09-13T16:00:00Z",
  type_of: "challenge",
  full_details: "Full hackathon schedule, judging rubric, and prizes breakdown.",
  published: true,
  bg_color_hex: "#7C3AED",
  remote_cover_image_url: "https://assets.example.com/banner.png",
  data: {
    location: "Houston, Texas, US",
    format: "IN-PERSON",
    external_registration_url: "https://hackrice.com"
  }
)

Delete an event

client.events.delete(12)

See Also:

Constant Summary collapse

OBJECT_NAME = 
"event"
RESOURCE_PATH = 
"/api/events"

Instance Attribute Summary

Attributes inherited from ForemObject

#requestor

Class Method Summary collapse

Instance Method Summary collapse

Methods included from APIOperations::Create

create

Methods included from APIOperations::List

list

Methods included from APIOperations::Retrieve

retrieve

Methods included from APIOperations::Update

update

Methods included from APIOperations::Delete

#delete, included

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

Class Method Details

.create(params = {}, opts = {}) ⇒ Event

Create a new event or upsert by matching slugs.

Automatically wraps flat parameters under the :event key expected by the API.

Parameters:

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

    event parameters

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

    per-request options

Returns:

  • (Event) —

    the newly created event



107
108
109
110
 
# File 'lib/forem/resources/event.rb', line 107

def self.create(params = {}, opts = {})
  payload = params.key?(:event) || params.key?("event") ? params : { event: params }
  super(payload, opts)
end

.update(id, params = {}, opts = {}) ⇒ Event

Update an existing event.

Automatically wraps flat parameters under the :event key expected by the API.

Parameters:

  • id (Integer, String) —

    event ID or slug

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

    attributes to update

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

    per-request options

Returns:

  • (Event) —

    the updated event



120
121
122
123
 
# File 'lib/forem/resources/event.rb', line 120

def self.update(id, params = {}, opts = {})
  payload = params.key?(:event) || params.key?("event") ? params : { event: params }
  super(id, payload, opts)
end

Instance Method Details

#save(params = {}, **opts) ⇒ Event

Save this event instance via the API.

Automatically wraps flat parameters under the :event key expected by the API.

Parameters:

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

    attributes to update

  • opts (Hash) —

    per-request keyword options

Returns:

  • (Event) —

    updated event instance



132
133
134
135
 
# File 'lib/forem/resources/event.rb', line 132

def save(params = {}, **opts)
  payload = params.key?(:event) || params.key?("event") ? params : { event: params }
  super(payload, **opts)
end