Q4Widgets API Documentation

q4.apiMashup

Widget for aggregating multiple types of Q4 private API data.

Latest Version Update: 1.12.11 
- added regFilings contentType (S&P only)
Script link
q4.apimashup.1.12.11.min.js
Source file
q4.apimashup.js, line 2
Requires

Options

contentSources Array.<Object>
An object containing content source objects, indexed by an ID string. Each content source object consists of the following options, plus any additional options made available by the specific content type.
Default value
"Financials": { type: 'financials', reportTypes: ['First Quarter', 'Second Quarter', 'Third Quarter', 'Fourth Quarter'], label: 'financials' }, 'Other: news': { type: 'news', tags: ['financials'], label: 'other' }, 'Other: webcast': { type: 'events', tags: ['financials'], label: 'other' }, 'Other: presentation': { type: 'presentations', tags: ['financials'], label: 'other' }, 'SEC: quarterly filing': { type: 'sec', symbol: SECCONFIG.cik, excludeNoDocuments: true, includeHtmlDocument: true, filingTypes: ['10-K', '10-K/A', '10-Q'], exchange: 'CIK', label: 'sec' }, "News": { type: 'news', loadShortBody: false, tags: ['earnings', 'financials'], label: 'news' },
Parameters
1. USE SEC option
Turned on using WIDGETSETUP.useSec boolean. This option will switch from uploaded Financial Documents to dynamically fed SEC documents for Quarterly Filings. If you wish to only pull in SEC documents where uploaded quarterly reports are absent, turn on WIDGETSETUP.onlyFillBlanksSec boolean.
2. OTHER CONTENT SOURCES option
Turned on using WIDGETSETUP.useOther boolean.
Press Release option
'news' items with tags ['financials'] and ['fin-2020-q1'], where 2020 and q1 are replaced with year and quarter
Earnings Webcast option
'events' items with tags ['financials'] and ['fin-2020-q1'], where 2020 and q1 are replaced with year and quarter. Uses webcast url.
Earnings Presentation option
'presentations' items with tags ['financials'], ['presentation'], and ['fin-2020-q1'], where 2020 and q1 are replaced with year and quarter.
Earnings Transcript Option 1 option
'presentations' items with tags ['financials'], ['transcript'], and ['fin-2020-q1'], where 2020 and q1 are replaced with year and quarter.
Earnings Transcript Option 2 option
'events' items with tags ['financials'] and ['fin-2020-q1'], where 2020 and q1 are replaced with year and quarter. Looks for attachment with 'transcript' anywhere in the title. If you wish to only pull in the above documents where uploaded Financials content is absent, turn on WIDGETSETUP.onlyFillBlanksOther boolean.
3. NEWS PREVIEW option
use "financials" tagging system instead of old "earnings" tagTurned on using WIDGETSETUP.useFinNewsTags Will show 'news' items with tags ['financials'] and ['fin-2020-q1'], where 2020 and q1 are replaced with year and quarter (Same as the item that will show in links sidebar)
startSource string
The ID of the content source to display when the widget is initialized. If this value is false or unset, display all sources. If there is a value, reloadYears will be triggered automatically whenever the source is changed.
Parameters
languageId string
A number representing which language to pull data from. By default the widget will attempt to auto-detect the language.
Parameters
Example
'1'
url string
The base URL to use for API calls. By default, calls go to the current domain, so this option is usually unnecessary.
Parameters
useJSONP boolean
When true, the API is changed to a JSONP format and can be called from an external source outside of a Q4 environment (ie. local machine, client's internal server)
Default value
false
Parameters
limit number
The maximum number of results to fetch from the server.
Default value
0
Parameters
skip number
The number of results to skip. Used for pagination.
Default value
0
Parameters
excludeSelection boolean
If set to false the 'Exclude from latest' option will be ignored for all sources
Default value
false
Parameters
fetchAllYears boolean
Whether the template should include items from all years, regardless of the current year.
Default value
false
Parameters
showAllYears boolean
Whether to include an "all years" option in template data and year selectors. If true, then "all years" will be the default year on first load; otherwise the most recent year will be the default.
Default value
false
Parameters
allYearsText string
The text to use for the "all years" option.
Default value
All
Parameters
startYear number
The year to display when the widget first loads. Default is to display items from all years if that option is enabled, otherwise the most recent year. A useful value you might want to pass is `(new Date()).getFullYear()`, which will display items from the current calendar year.
Parameters
forceStartYear boolean
Whether to start with `startYear` even if there are no documents for that year.
Default value
false
Parameters
showFuture boolean
Whether to fetch items dated in the future.
Default value
true
Parameters
showPast boolean
Whether to fetch items dated in the past.
Default value
true
Parameters
tags Array.<string>
A list of tags to filter by.
Parameters
titleLength number
The maximum length of an item's title. Zero for no limit.
Default value
0
Parameters
bodyLength number
The maximum length for the body, or zero for unlimited.
Default value
0
Parameters
shortBodyLength number
The maximum length for the short body, or zero for unlimited.
Default value
0
Parameters
shortTypes Object
A map of short names for each financial report subtype, for use in templates for financial reports and events.
Parameters
dateFormat stringObject
A date format string, which can be used in the template as `{{date}}`. Can alternately be an object of format strings, which can be accessed with `{{date.key}}` (where key is the object key corresponding to the string you want to use). By default, dates are formatted using jQuery UI's datepicker.
Default value
MM d, yy
Parameters
Example
'MM d, yy'
Example
{
    full: 'MM d, yy',
    short: 'mm/dd/y',
    month: 'MM',
    day: 'd'
}
useMoment boolean
Whether to use Moment.js to format dates instead of datepicker. Only takes effect if the Moment.js library has been included.
Default value
false
Parameters
sortAscending boolean
Whether to sort items in ascending chronological order.
Default value
false
Parameters
years Array.<number>
An array of years to filter by. If passed, no items will be displayed unless they are dated to a year in this list.
Parameters
minYear number
The earliest year to display items from.
Parameters
maxYear number
The latest year to display items from.
Parameters
minDate Date
The earliest date to display items from.
Parameters
maxDate Date
The latest date to display items from.
Parameters
defaultThumb string
A URL to a default thumbnail, in case an item has none.
Parameters
template string
A Mustache.js template for the overall widget. This option is not required; you can also use `yearTemplate` and item templates to build the widget on top of existing layout. The following tags are available: - `{{#contentSources}}` An array of content sources, each with these subtags: - `{{id}}` The ID string for this content source. - `{{label}}` The label for this content source. - `{{#sourcesWithItems}}` Like `{{contentSources}}` but only sources with items. - `{{#years}}` An array of years for the navigation, each with these subtags: - `{{year}}` The display label of the year (e.g. `"2015"`, `"All Years"`) - `{{value}}` The internal value of the year (e.g. `2015`, `-1`) - `{{#items}}` An array of items for this year, with the same format as the "all items" array. - `{{#yearsWithItems}}` Like `{{years}}` but with only years that have items. - `{{#items}}` An array of all items. Each item has a number of available subtags, which vary depending which content type you are using. Content types and their subtags are documented later in this file. If you are mixing different content types, it is recommended to use the `itemContainer` option and set templates separately for each content source.
Parameters
Example
'<ul class="years">' +
    '{{#years}}<li>{{year}}</li>{{/years}}' +
'</ul>' +
'<h1>{{title}}</h1>' +
'<ul class="items">' +
    '{{#items}}<li><a target="_blank" href="{{url}}">{{title}}</a></li>{{/items}}' +
    '{{^items}}No items found.{{/items}}' +
'</ul>'
append boolean
Whether to append the main template to a `
` inside the widget container, or replace the container's contents entirely.
Default value
true
Parameters
cssClass string
An optional CSS class to apply to the widget container, or if `append` is true, to the `
` containing the main template.
Parameters
loadingClass string
A CSS class to add to the widget while data is loading. This can be used to show and hide elements within the widget.
Parameters
loadingMessage string
A message or HTML string to display while first loading the widget. See also `itemLoadingMessage`.
Default value
<p class="module_loader"><i class="q4-icon_spinner"></i><span class="sr-only">Loading ...</span></p>
Parameters
yearContainer string
A selector for the year navigation container. Use this if you don't want to use the `template` option to draw the widget, but you still want to generate a list of years. You must also pass `yearTemplate` for this to have any effect.
Parameters
yearTemplate string
A Mustache.js template for a single year. If this and `yearContainer` are passed, this will be used to render each option in the year navigation, which will be attached to the widget at `yearContainer`. See the `template` option for available tags.
Parameters
Example
'<li>{{year}}</li>'
Example
'<option value="{{value}}">{{year}}</option>'
yearTrigger string
A CSS selector for year trigger links. If passed, any elements in the widget matching this selector will become clickable links that filter the displayed items by year. Usually you'll want to point this to an element in the template's `{{years}}` loop. Note that this doesn't automatically generate the year links; you can do that in the template.
Parameters
Example
'a.yearLink'
yearSelect string
A CSS selector for a year selectbox. This behaves like the `yearTrigger` option, except instead of pointing to individual links, it should point to a `` or similar form element. When the element's value changes, the value will be used as a space- or comma-separated list of tags to filter the items by.
Parameters
Example
'select.sourceDropdown'
tagSelect string
A CSS selector for a tag selectbox or text input. This should point to a `` or similar form element. When the element's value changes, the value will be used as a space- or comma-separated list of tags to filter the items by.
Parameters
Example
'select.tagDropdown'
Example
'input.tagList'
activeClass string
The CSS class to add to a selected year trigger.
Default value
js--selected
Parameters
itemContainer string
A selector for the items container. Use this if you want to redraw only the item list at initialization and when the year is updated, instead of redrawing the entire widget. This is recommended if using a set of different content types, so that each content type can use its own item template.
Parameters
itemTemplate string
A Mustache.js template for a single item. This can be overridden by the `template` option on individual content sources. If this and `itemContainer` are passed, this will be used to render the items list, and it will be attached to the widget at `itemContainer`. When the year changes, only this part of the widget will be redrawn, instead of the entire thing. See the `template` option for available tags.
Parameters
Example
'<li>' +
    '<img class="thumb" src="{{thumb}}">' +
    '<span class="date">{{date}}</span>' +
    '<a href="{{url}}" class="title">{{title}}</a>' +
'</li>'
itemLoadingClass string
A CSS class to add to the widget while loading items. This can be used to show and hide elements within the item container. You must also pass `itemContainer` for this to have any effect. By default it is the same as `itemLoadingMessage`.
Parameters
itemLoadingMessage string
A message or HTML string to display while loading items. You must also pass `itemContainer` for this to have any effect. By default it is the same as `loadingMessage`.
Parameters
itemNotFoundMessage string
A message or HTML string to display in the items container if no items are found.
Default value
<p><i class="q4-icon_warning-line"></i> No items found.</p>
Parameters
onYearChange function
A callback that fires when the display year changes.
Parameters
event Event
The triggering event object.
data Object
A data object with these properties: - `year` The year to be displayed.
onTagChange function
A callback that fires when the list of tags to display changes.
Parameters
event Event
The triggering event object.
data Object
A data object with these properties: - `tags` The array of tags to filter by.
onContentSourceChange function
A callback that fires when the active content source changes.
Parameters
event Event
The triggering event object.
data Object
A data object with these properties: - `contentSources` An array of IDs of currently displayed content sources.
beforeRender function
A callback that fires before the full widget is rendered.
Parameters
event Event
The event object.
templateData Object
The complete template data.
beforeRenderNoItems function
A callback that fires before the no items message is rendered.
Parameters
event Event
The event object.
templateData Object
Template data for the items list.
beforeRenderItems function
A callback that fires before the items list is rendered. This only fires if `itemContainer` is set.
Parameters
event Event
The event object.
templateData Object
Template data for the items list.
itemsComplete function
A callback that fires after the item list is rendered. This only fires if `itemContainer` is set.
Parameters
event Event
The event object.
complete function
A callback that fires after the entire widget is rendered.
Parameters
event Event
The event object.

Methods

reloadYears
Reload the year list based on the new content source, this will also reload the items. This function is triggered automatically if a startSource is defined.
reloadItems
Reload all items in the widget, maintaining the current year, tags and other options. This is run automatically by `setYear`, `setTags` and `setContentSource` and `reloadYears`, and can be run manually after using the `option` method to change other options, such as press release category.
setContentSource
Display items from a specific content source as passed in the options, or all of them. This will refetch the list of items if necessary.
Parameters
sourceID string
The ID of the source to use, or `null` for all sources.
event Event
The triggering event, if any.
setYear
Display items from a particular year. This will refetch the list of items if necessary.
Parameters
year number
The year to display, or -1 for all years.
event Event
The triggering event, if any.
setTags
Display items with at least one of a particular set of tags. This will refetch the list of items if necessary.
Parameters
tags Array.<string>
The array of tags to look for.
event Event
The triggering event, if any.