| InstantCal API: |
|
InstantCal is configured using a very simple API (Application Programming Interface).
Default configuration values are generated when you Create an Event Calendar.
The configuration values may be changed to control the appearance and behaviour of
InstantCal in detail.
|
|
The InstantCal API is described in the following sections:
|
| |
| 1. Setup |
|
Setup describes how to embed InstantCal in a web page.
|
| |
| 2. API Overview |
The InstantCal API is defined by a URI and a set of options in the HTML embed code of the InstantCal Setup.
The URI is:
http://cdn.instantcal.com/cvir.html?
|
| |
|
Each option has a name and a value and is specified by a 'name=value' pair.
|
|
Multiple options are separated by an ampersand ('&').
|
| |
Example: Calendar with a color scheme (theme) of gray-gradient (xgy) and a display format (gtype) of month (cv_monthGrid)
The URI and options:
http://cdn.instantcal.com/cvir.html?theme=xgy&file=http://instantcal.com/categories.ics>ype=cv_monthGrid
|
are used in the following HTML embed code:
<iframe src='http://cdn.instantcal.com/cvir.html?theme=xgy&file=http://instantcal.com/categories.ics>ype=cv_monthGrid' allowTransparency=1 scrolling='no' frameborder=0 height=600 width=600></iframe>
|
|
Note that the dimensions of the calendar (in pixels) are defined by the IFrame settings height=600 and width=600.
|
|
IFrame transparency is also enabled so that any background from the web page is displayed in areas not covered by the calendar.
|
| |
| 3. Calendar Data Sources |
|
Calendar data may exist in many formats (e.g. iCal, RSS).
|
|
Regardless of the format, the source (or sources) of calendar data are
always specified by the file option, which has a URI as its value.
The URI may contain information about the calendar data format.
|
The following calendar data formats are supported:
- iCal - an iCalendar file
- Webcal - a webcal calendar
- RSS - an RSS feed
- Twitter - a Twitter feed
|
| API Data Options |
| Description |
Name |
Value |
| iCal | file | http://...iCal file... |
| Webcal | file | webcal://...Webcal file... |
| RSS | file | http://...RSS feed... |
| Twitter | file | http://twitter.com/...?file=...&dtype=twitter |
|
|
iCal format is the standard for specifying calendar data. This format is available from most web-based calendar services.
|
|
Webcal is an alternate 'scheme' for accessing iCal format data. Some web-based calendar services export calendar data using webcal.
|
|
RSS is associated with newsfeeds and blogs. These data streams frequently contain dated information that may be represented
in calendar formats. InstantCal automatically translates RSS into a calendar format.
|
|
Twitter feeds in RSS or JSON format may be automatically translated into a calendar format.
|
|
Note: more than one file option may be used to 'overlay' the display of multiple calendars.
|
| |
| 4. Display |
| |
| A) Organization |
Calendars are organized in one of two ways:
- Navigated (navigate -> group -> item)
- Grouped (group -> item)
|
|
The Navigated organization has three levels of display; navigation (ntype option), group (gtype option), and item.
The navigation display allows a date to be selected, and a group of calendar events
displayed. The group display shows a group of calendar events.
No group is displayed if the group is empty ('gtype=').
The item display shows a single calendar event in detail.
|
|
The Grouped organization has two two levels of display; group (gtype option), and item.
The group display shows a group of calendar events.
No group is displayed if the group is empty ('gtype=').
The item display shows a single calendar event in detail.
|
|
The calendar organization is not set directly, but is controlled by the display formats described below.
|
| |
| B) Display Formats |
The calendar display formats are listed in the table below.
|
|
Visual effects (described later) may be set for display formats having values in the 'Effects' column.
Visual effects include scroll, slide, fade, or rotate.
|
| API Display Options (navigation/group/item) |
| Description |
Name |
Value |
Effects |
| Date picker (month) | ntype | cv_datepicker | |
| Date picker (quarter) | ntype | cv_datepicker3 | |
| Date picker (semi-annual) | ntype | cv_datepicker6 | |
| Date picker (annual) | ntype | cv_datepicker12 | |
| | | |
| Month | gtype | cv_monthGrid | |
| Day | gtype | cv_dayGrid | |
| 3 Day | gtype | cv_dayGrid3 | |
| 5 Day | gtype | cv_dayGrid5 | |
| 7 Day | gtype | cv_dayGrid7 | |
| Multi-view (month/day/list) | gtype | cv_multiView | |
| Preview | gtype | cv_simpleList | s, l, f, r |
| List - Summary | gtype | cv_listSummary | s, l, f, r |
| Labeled List - Summary | gtype | cv_labeledListSummary | s, l, f, r |
| Labeled List Long - Summary | gtype | cv_labeledListSummaryLong | s, l, f, r |
| Table | gtype | cv_listTable | s, l, f, r |
| Ticker (one-liner) | gtype | cv_oneLiner | s, l, f, r |
| | | |
|
| |
| Sub-formats (Month) |
| API Display Options (month sub-format) |
| Description |
Name |
Value |
| Wrap | gwrap | 0 or 1, display multi-line event summary (default: 0) |
| Border | geborder | 0 or 1, hide event border (default: 1) |
| Time | etimes | 0 or 1, event time in event summary (default: 0) |
|
| |
| Sub-formats (List-style) |
|
A period and subperiod may be set for list-style display formats (cv_simpleList, cv_listSummary, cv_labeledListSummary, cv_labeledListSummaryLong, cv_listTable).
|
|
The period specifies the length of time over which a screen of events is displayed.
|
|
The subperiod further limits events displayed to either a single event (gsubperiod=event) or future events only (gsubperiod=upcoming).
|
| API Display Options (list sub-format) |
| Description |
Name |
Value |
| Period | gperiod | year, month, week, day |
| Subperiod | gsubperiod | event, upcoming |
| Date | gehdate | 0 or 1, display day for events (1: default) |
| Time | gehtime | 0 or 1, display in-line event time (1: default) |
|
| |
| C) Visual Effects |
|
Some display formats support the special visual effects scroll, slide, fade, rotate, and ticker.
|
|
Scrolling may be vertical (like a television program listing) or horizontal (like a stock ticker).
|
|
Sliding is a special form of scrolling where the scroll options are set to simulate a 'sliding door' (e.g. gspausen=0&gspaused=3000&gsrate=2000).
|
|
Fading in and out is an alternative way to update the display. Slow fades are are less obtrusive; rapid fades provide faster updates.
|
|
|
|
Rotation is a special form of fading where the fade time (or 'rotate time') is short for fast fade-in/fade-out (e.g. gfnext=10).
This simulates a slide show.
|
|
Note: Ticker (or crawler) is a one-line display with horizontal scroll.
|
| API Display Options (visual effects) |
| Description |
Name |
Value |
| Scroll | geffect | scroller |
| - direction | gsdir | left, right, up, down |
| - loops | gsloops | number of cycles before stopping |
| - scroll rate | gsrate | scrolling movement interval (in milliseconds) |
| - pause duration | gspaused | length of periodic pauses while scrolling (in milliseconds) |
| - pause interval | gspausen | time until next pause while scrolling (in milliseconds) |
| | |
| Slide | geffect | scroller |
| - direction | gsdir | left, right, up, down |
| - loops | gsloops | number of cycles before stopping |
| - scroll rate | gsrate | sliding movement interval (in milliseconds) |
| - pause duration | gspaused | length of periodic pauses while sliding (in milliseconds) |
| - pause interval | gspausen | time until next pause while sliding (in milliseconds, usually 0) |
| | |
| Fade-in/fade-out | geffect | fader |
| - loops | gfloops | number of cycles before stopping |
| - fade time | gfnext | fade cycle time (in milliseconds) |
| - pause duration | gfpaused | length of pause when faded-in (in milliseconds) |
| | |
| Rotate | geffect | fader |
| - loops | gfloops | number of cycles before stopping |
| - rotate time | gfnext | rotate cycle time (in milliseconds) |
| - pause duration | gfpaused | length of pause while displayed (in milliseconds) |
| - rotate range | gfrange | period of events covered by rotation cycle(month, week) |
|
| |
| D) Color Scheme (Theme) |
|
General color appearance of the navigated, grouped, and item displays may be set by the theme option.
Several pre-defined themes are available in blend or flat colors.
Or, a custom monotone color may be selected.
|
| API Display Options (color scheme) |
| Description |
Name |
Value |
| Gray | theme | xgy |
| Red | theme | xre |
| Blue | theme | xbl |
| Yellow | theme | xye |
| Green | theme | xgr |
| Gray (flat) | theme | gy |
| Red (flat) | theme | re |
| Blue (flat) | theme | bl |
| Yellow (flat) | theme | ye |
| Green (flat) | theme | gr |
| Custom color | theme | 6-digit hex code (e.g. aa40cc) |
| Custom background color | bcolor |
6-digit hex code (e.g. aa40cc)
Note: requires Custom color
|
|
| |
| E) Additional options |
|
The appearance of each display may be further controlled by setting additional options.
These options may depend on the type of display, according to the tables below.
|
| API Display Options (general) |
| Description |
Name |
Value |
| Rounded corners | border_radius | number of pixels for rounding (e.g. 5) |
| Calendar color | ccolor | 6-digit hex code (e.g. red=ff0000, green=00ff00) |
| Calendar name | cname | Name of calendar |
| | |
| Event border | geborder | 0 or 1, hide event border (default: 1) |
| Event categories | ccategory | Category name(s) |
| Event category color | ccategory_color | 6-digit hex code (e.g. red=ff0000) |
| Event categories selected | ccategory_sel | Default Category name(s) selected |
| Event day list order | dateorder | 0, late-to-early; 1, early-to-late (default) |
| Event time list order | timeorder | 0, late-to-early; 1, early-to-late (default) |
| | |
| Day/Month display order | ddmm | 1, mmdd; 0, ddmm (default) |
| Start day-of-week | wkst | Day-of-week (e.g. Mon or 1) [month grid only] |
| Map Service | map | google (Google Maps) or yahoo (Yahoo Maps, default) |
| 24-hour time | time24 | 0 or 1, display event times in 24-hour format |
| Timezone | timezone_def | Area/Location (e.g. America/New_York)
Show non-floating times in this timezone.
Reference: Wikipedia ZoneInfo |
|
| |
| API Display Options (navigation-specific) |
| Description |
Name |
Value |
| Navigation day active color | n_activecolor | 6-digit hex code (e.g. red=ff0000) |
| Navigation font size | n_font_size | font size, in pixels (e.g. 12px) |
| Navigation padding | n_padding | day cell padding, in pixels (e.g. 2px) |
|
Note: Display sizes may be set in pixels or percentages.
When set in pixels, a 'px' suffix must be used (e.g. '200px').
When set in percentages, no suffix is used (e.g '100' means '100 percent').
|
| |
| 5. Viewer Controls |
|
InstantCal viewers may be given permission to customize calendars, if certain options are used
in the HTML embed code.
|
|
If event category options are specified,
a set of categories (defined by 'ccategory' parameters) is displayed.
|
|
If timezone options are specified,
a menu of timezones is displayed (see Timezones for details)
|
| API Viewer Control Options |
| Description |
Name |
Value |
| Event category selector | ccategory_type | select (pull-down menu) or checkbox |
| Timezone type | timezone_type | select (pull-down menu) |
|
| |