ic-portal

This module aims to provide a unified interface for interacting with administration panels designed by I&C Digital for college events, deployed for use at third-level institutions in Ireland.

Current functoinality is event retrieval.

Installation

npm install ic-portal --save

Supported Sources/Functionality

• UCC Societies
  • Events calendar

Basic Usage

This example grabs all events running in the next week, hosted by any society at University College, Cork.

First, we create a new Portal object.

const Portal = require("ic-portal")
const portal = new Portal("ucc-societies")

This object represents the administration panel used by organisations/hosts within the named institution, and allows us to retrieve and send data.

Let's get a list of events run by any society, from the current date and up to seven days in the future:

let start = Date.now()
let end = dayjs().add(7, "day")
 
let events
 
try {
    events = await portal.events.all(start, end)
} catch (e) {
    console.log("Error retrieving events! %s", e)
}

If all goes well, we should have a list of all the events that societies are hosting in the next week!

Let's see what the first event might look like:

console.log(JSON.stringify(events))

{
    "title": "KTV Karaoke",
    "host": "Chinese",
    "start": "2020-03-02T19:00:00.000Z",
    "end": "2020-03-02T23:00:00.000Z",
    "allDay": false,
    "location": "Upstairs Cafe Student Centre",
    "onCampus": true,
    "type": "music",
    "description": "Need something to relieve the stress of midterms and assignments coming up soon? Korean and Chinese Societies are hosting a KTV/Karaoke Night this coming Monday in the Upstairs Café!!\n\nCome along and sing your heart out to your favourite tunes, bops, bangers and absolute slappers with us. Any language is okay as long as you're havin' a good time"
}

If we want to grab a list of events hosted by a specific group, we can specify that too:

try {
    events = await portal.events.byHost("Pirate", start, end)
} catch (e) {
    console.log("Error retrieving events! %s", e)
}

Or multiple:

try {
    events = await portal.events.byHosts(["Pirate", "Dodgeball"], start, end)
} catch (e) {
    console.log("Error retrieving events! %s", e)
}

API

Terminology used:

• "host" means the society, club, or other organisation that is hosting a particular event.

Portal(endpoint)

Represents an endpoint/portal of a particular institution where data can be obtained.

• endpoint is one of ucc-societies.

const { Portal } = require("ic-portal")
const portal = new Portal("ucc-societies")

.events

Reference to an Events object.

Events(portal)

An interface to interact with the events calendar. Not intended for instantiation outside of this module's source code; one of these objects will be created for you when you create a Portal object.

.all(start, end, extended=true)

Obtains events from all hosts within the institution. Returns an array of Event objects.

• start is a Date object of when to start searching for events.
• end is a Date object of when to stop searching for events.
• extended attempts to obtain as much information about each event.

Warning: Please set extended to false if the date range is high (e.g. >7 days). In order to grab extended information, this function makes an additional HTTP request for every event.

.byHost(host, start, end, extended=true)

Obtains events from a specified host within the institution. Returns an array of Event objects.

• host is either a String, Integer, or Array representing host(s) to search.
• start is a Date object of when to start searching for events.
• end is a Date object of when to stop searching for events.
• extended attempts to obtain as much information about each event.

If host is a string, this function will return the events for the first host name that contains host as a substring.

If host is an integer, this function will use host as the exact ID and return events matching it.

If host is an array, this function will treat each element as representing a host (either a string or integer), and will include them all in the search.

Warning: Please set extended to false if the date range is high (e.g. >7 days). In order to grab extended information, this function makes an additional HTTP request for every event.

.byHosts(...args)

Same as .byHost().

.hosts(refresh=false)

Grabs a list of possible event hosts, and their associated identifiers used for querying.

This method sets the internal _hosts property as well as returning the list of hosts.

If the _hosts property is already set, this method will return the cached version. If it's set and refresh is set to true, this function will re-obtain the hosts list and update the cache.

Event(obj)

This object represents a single event. obj is an object returned by the server.

Properties:

• title (String): title of the event
• host (String): host of the event (what society/club is organising it)
• plainDescription (String): Description of the event without any additional formatting
• markdownDescription (String): Description of the event formatted as Markdown
• htmlDescription (String): Original description of the event as HTML
• start (Date): the date/time the event is starting
• end(Date): the date/time the event is ending
• allDay (Boolean): whether or not the event is occuring all day
• location (String): the location of the event
• onCampus (Boolean): whether or not the event is happening on campus or off campus
• type (String): what kind of event it is, from the following list:
  • general-meeting: Any kind of general meeting, i.e. AGM or EGM
  • workshop-or-training: An event representing an educational workshop or training session
  • guest-speaker: An event centered around hosting a local/international guest speaker
  • social: A social event, including social balls
  • competition-or-excursion: An event which is run as a competition in which members of the host are competing
  • music: An event centered around music, e.g. a concert
  • performance-or-screening: A performance or screening, e.g. movie screenings, theatrical performances
  • other: None of the above

Hosts(hosts)

This object represents a list of hosts, and is mainly just a wrapper class to allow searching through the list.

findFirst(name)

Finds the first host whose name contains name as a substring.

If not found, returns null. If found, returns an object containing:

• id: The identifier representing the host, used as a reference in querying.
• text: The full name of the host.

findAll(name)

Finds all hosts whose name contains name as a substring.

If not found, returns []. If found, returns an array of objects containing:

• id: The identifier representing the host, used as a reference in querying.
• text: The full name of the host.

getName(name)

Returns a host with the exact name matching `name.

If not found, this method throws an error. If found, returns an object containing:

• id: The identifier representing the host, used as a reference in querying.
• text: The full name of the host.

getId(id)

Returns a host with the exact id matching id.

If not found, this method throws an error. If found, returns an object containing:

• id: The identifier representing the host, used as a reference in querying.
• text: The full name of the host.