Q4Widgets API Documentation

q4.api

This page contains all of the global options which apply to each of our Q4 Content Widgets (see link list below). These widgets are powered by our private and public CMS content API's and rendered using mustache.js through the selected template option.

Each widget will have options which are unique to that type of content, and are described in more detail with examples on their individual documentation pages (linked below).

Latest Version Update: 1.13.4 
- Updated sec functionality.
- Added option to filter by filing type (filingTypes).
- Renamed previous filingTypes array to filingGroups.
- Updated Documentation.
- Fix beforeRenderItems data structure
Script link
q4.api.1.13.6.min.js
Source file
q4.api.js, line 2
Requires

This is an abstract widget; it isn't meant to be instantiated directly. Use one of its child widgets.

Child widgets have all the options and methods of this widget, but may add their own as well. See the child widget's documentation for additional options or methods. This widget has the following child widgets:

Options

url string
The base URL to use for API calls. By default, calls go to the current domain, so this option is usually unnecessary.
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
forcePublic boolean
When true, the url can be set to pull data from another Q4 website
Default value
false
languageId string
A number representing which language to pull data from. By default the widget will attempt to auto-detect the language.
Example
'1'
limit number
The maximum number of results to fetch from the server.
Default value
0
limitSort number
Requires limit to be set. This option will determine the sorting order from within the limited items. This is most commonly used with showing a limited number of upcoming events. Ex. If you want to show the 3 most recent upcoming events, use a limit of 3 and change the sort order to descending.
Default value
0
Example
0 = Descending order, 1 = Ascending order
skip number
The number of results to skip. Used for pagination.
Default value
0
excludeSelection boolean
If set to true, only content that does not have the 'Exclude from latest' checkbox checked in the CMS will be shown.
Default value
false
fetchAllYears boolean
Whether the template should collect items from all years, regardless of the current year. This will mean items from all years are available for use in the template option and beforeRender callback.
Default value
false
showAllYears boolean
If true, the widget will force fetchAllYears to be true and thus items from all years will be available for use in the template and beforeRender callback. In addition, the widget will load content from all years by default and there will be a new option for "all years" in the year template. The "all years" text in the template can be changed with the allYearsText option. If false, the most recent year will be the default year on first load and only specific years will be available in the year template.
Default value
false
allYearsText string
The text to use for the "all years" option.
Default value
All
startYear number
The year to display when the widget first loads. Default is to display items from the most recent year, unless showAllYears is true. A useful value you might want to pass is new Date().getFullYear(), which will display items from the current calendar year.
Example
2016
Example
new Date().getFullYear()
forceStartYear boolean
Whether to start with startYear even if there are no documents for that year.
Default value
false
isTimeZoneKey object
A JSON object to convert custom time zones back to the default This is needed only when using isFuture or isPast in the template. If the custom timezone is not defined in this list, you may see an "invalid date" error.
Default value
{ 'PT': 'PST', 'MT': 'MST', 'CT': 'CST', 'ET': 'EST', 'AT': 'AST', 'GT': 'GST', 'GMT': 'GMT', 'BST': 'GMT' }
tags Array.<string>
A list of tags to filter by.
Default value
[]
Example
['featured', 'earnings'],
titleLength number
The maximum character length of an item's title. Use Zero for no limit.
Default value
0
Example
100
bodyLength number
The maximum character length for the body text, or zero for unlimited.
Default value
0
Example
100
shortBodyLength number
The maximum character length for the short body text, or zero for unlimited.
Default value
0
useMoment boolean
If time is required in the widget template, change this option to true. This will mean the widget uses Moment.js to format dates and times instead of datepicker. Note that this option will only work if the Moment.js library has been included on the page. If true, the dateFormat option must be changed to use MomentJS date format naming rules.
Default value
false
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). In a widget which requires a date and time you would want to enable the useMoment option and render the time as {{date.time}} in the template.
Common Datepicker Format options:
  • d = day of month (no leading zero)
  • dd = day of month (two digit)
  • D = day name short
  • DD = day name long
  • m = month of year (no leading zero)
  • mm = month of year (two digit)
  • M = month name short
  • MM = month name long
  • y = year (two digit)
  • yy = year (four digit)
  • @ = Unix timestamp (milliseconds since 01/01/1970)
Common MomentJS Format options:
  • D = day of month (no leading zero)
  • DD = day of month (two digit)
  • ddd = day name short
  • dddd = day name long
  • M = month of year (no leading zero)
  • MM = month of year (two digit)
  • MMM = month name short
  • MMMM = month name long
  • YY = year (two digit)
  • YYYY = year (four digit)
  • x = Unix timestamp (milliseconds since 01/01/1970)
  • h = hour (12hr, no leading zero)
  • hh = hour (12hr, two digit)
  • mm = minute (two digit)
  • A = AM/PM
  • a = am/pm
Default value
MM d, yy
Example
'MM d, yy' // datepicker format
Example
{
    date: 'MM D, YYYY',
    time: 'hh:mm a'
}
sortAscending boolean
Whether to sort items in ascending chronological order.
Default value
false
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.
Default value
[]
Example
[2014, 2015, 2018]
minYear number
The earliest year to display items from.
Example
2015
maxYear number
The latest year to display items from.
Example
2018
minDate Date
The earliest date to display items from.
Example
"2018-01-24T01:20:00" // Jan 24, 2018 @ 1:20am
maxDate Date
The latest date to display items from.
Example
"2018-01-24T22:20:00" // Jan 24, 2018 @ 10:20pm
defaultThumb string
A URL to use for a default thumbnail, in case an item has none.
Example
'/files/images/cover-thumb.png'
append boolean
Whether to append the main template to a <div> inside the widget container, or replace the container's contents entirely.
Default value
true
cssClass string
An optional CSS class to apply to the widget container, or if append is true, to the <div> containing the main template.
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.
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>
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.
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.
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.
Example
'a.yearLink'
yearSelect string
A CSS selector for a year dropdown. This behaves like the yearTrigger option, except instead of pointing to individual links, it should point to a <select> or similar form element. Note that this doesn't automatically fill the box with <option>'s; Utilize the yearTemplate option or specify a container in the template to generate the options inside the select.
Example
'.yearsDropdown'
noYearsMessage string
An HTML string to display in the year container if no years are found.
Example
'<option value="-1">N/A</option>'
tagSelect string
A CSS selector for a tag dropdown or text input. This should point to a <select>, <input> 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.
Example
'select.tagDropdown'
Example
'input.tagList'
tagTrigger string
A CSS selector for a tag trigger links. If passed, any elements in the widget matching this selector will become clickable links that filter the displayed items by tag. Note that this doesn't automatically generate the list of tags, it only acts the functionality to filter;
Example
'a.tagList'
activeClass string
The CSS class to add to a selected year and tag trigger.
Default value
js--selected
itemContainer string
A selector for the items container. An alternative to the generic template option, use this if you want to redraw only the item list. This will render the items using the itemTemplate at initialization as well as each time a year or tag is updated (instead of redrawing the entire widget).
Example
'.module_container--content'
itemTemplate string
A Mustache.js template for a single item, which will be reused for each item in the data array. For example, use this option to define a template for a single event. The widget will then re-use this template for every event that exists matching the widget criteria. The result is that all events in this widget are now structured in the same way on the page. If this and itemContainer are passed, this template will be used to render the items list inside the itemContainer. When using yearSelect or yearTrigger and the year changes, only this part of the widget will be redrawn. The same functionality applies for tagSelect and tagTrigger. Read more about configuration options in the template option below. 

itemTemplate: (
 '<div class="module_item-wrap background--grey">' +
   '<div class="module_date-time"><span class="module_date-text">{{date}}</div>' +
   '<div class="module_headline">' +
     '<a class="module_headline-link" href="{{url}}">{{title}}</a>' +
   '</div>' +
   '<div class="module_links module_q4-icon-links">' +
     '<a class="module_link" href="{{docUrl}}" target="_blank">Download PDF <span class="sr-only">(opens in new window)</span></a>' +
   '</div>' +
 '</div>'
)
itemLoadingClass string
A CSS class to add to the widget while loading items inside the itemContainer. This can be used to show and hide elements within the item container. You must also pass itemContainer and itemTemplate for this to have any effect. By default it is the same as itemLoadingMessage.
itemLoadingMessage string
A message or HTML string to display while loading items inside of the itemContainer. You must also pass itemContainer and itemTemplate for this to have any effect. By default it is the same as loadingMessage.
itemNotFoundMessage string
A message or HTML string to display in the itemContainer if no items are found.
Default value
<p><i class="q4-icon_warning-line"></i> No items found.</p>
template string
The template option determines the layout of the widget once it is rendered on the page. The mustache.js plugin is used to render the template strings into full HTML, based on the data available from the API call. Using the template option is not required, as long as the yearTemplate and/or itemTemplate are used instead. The desired structure should be listed as strings containing html elements, with mustache variables to indicate where data should be used.

Important Notes:
  • HTML elements should be listed as strings and combined with plus sign at the end of each string. For example: '<span>Content text</span>' +
  • The last string in the template should not include a plus sign at the end as it will return an error
  • Mustache variables are shown in curly brackets, ex. {{title}} this content will be replaced with the value it represents in the API.
  • Variables with two curly brackets are rendered as text. Variables with three curly brackets (ex. {{{body}}} ) are rendered as HTML.
  • Arrays of data can be accessed with # and closed with /. For example using {{#docs}} in a widget template will allow you to access an array of documents inside of a single content item.
  • The value of the variable is specific to the array in which it is contained. For example, {{title}} inside of {{#docs}} will refer to the document title, but if it is listed outside of the array it would refer to the title of the content item (ex. event title).
  • If/Else logic can be applied using # and ^ before a variable. See the example code at the bottom of this section.
    • {{#items}} If items exist, access them and do something.
    • {{^items}} If items do not exist, do something else

The following tags are available:

  • {{#years}} An array of years for the navigation. Each year has 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}} works similar to {{years}} but will only return the years that have items. This can be used to avoid showing "phantom" years that have no content.
  • {{#items}} An array of all items. Each item has a number of available subtags, which vary depending which child widget you are using.

For a list of variables available for templates, check the documentation for the specific child widgets: 
template: (
 '<select class="years">' +
  '{{#years}}' +
    '<option value="{{value}}">{{year}}</option>' +
  '{{/years}}' +
 '</select>' +
 '<h4>{{title}}</h4>' +
 '<ul class="items">' +
  '{{#items}}' +
    '<li><a href="{{url}}">{{title}}</a></li>' +
  '{{/items}}' +
  '{{^items}}No items found.{{/items}}' +
 '</ul>'
)
onYearChange function
A callback that fires when the list of years to display changes.
Parameters
event Event
The triggering event object.
data Object
A data object containing the newly selected year. Example: { year: 2015 }
onTagChange function
A callback that fires when the tag filtering selection changes.
Parameters
event Event
The triggering event object.
data Object
A data object containing the array of tags to filter by. Example: { tags: { 0: "featured", 1: "slider" } }
beforeRender function
A callback that fires before the full widget is rendered. It is generally used to restructure/manipulate data before being passed into the template option.
  • This function runs only once, when widget is first loaded on the page
  • Can be used with any of the widget template options (template, yearTemplate and itemTemplate)
  • This callback is not triggered by yearSelect/yearTrigger or tagSelect/tagTrigger actions.
  • Can be used in conjunction with itemsComplete callback, but it will run after itemsComplete is finished.
Parameters
event Event
The event object.
templateData Object
The complete template data. Example: { items: [{...}, {...}], years: [{...}, {...}], yearsWithItems: [{...}, {...}] }
beforeRenderItems function
A callback that fires before the items list is rendered. It is commonly used to manipulate specific entries in the items array, such as overwriting a URL with a document path.
  • This function can run multiple times, it is triggered by user actions and methods.
  • Runs only if itemContainer and itemTemplate are defined.
  • This callback is automatically triggered when yearSelect/yearTriggeror tagSelect/tagTrigger are activated.
  • Will always run after the beforeRender callback if both are used.
Parameters
event Event
The event object.
templateData Object
Template data for the items list. Example: { items: [{...}, {...}, {...}] }
beforeRenderYears function
A callback that fires before the years are rendered.
  • This function only runs once, when the widget is first loaded on the page.
  • The function can be triggered to run again by using the reloadYears method.
  • Runs only if yearContainer and yearTemplate are defined.
  • Will always run before the beforeRender, beforeRenderItems, itemsComplete and complete callbacks.
Parameters
event Event
The event object.
templateData Object
Template data for the years list. Example: { items: [2018, 2017, 2016, 2015, 2014] }
itemsComplete function
A callback that fires after the item list is rendered. Often used to trigger item-specific scripts or plugins to run, such as Pager.
  • This function can run multiple times, it is triggered by user actions and methods.
  • Runs only if itemContainer and itemTemplate are defined.
  • This callback is automatically triggered when yearSelect/yearTriggeror tagSelect/tagTrigger are activated.
  • Will always run before the complete callback if both are used.
Parameters
event Event
The event object.
complete function
A callback that fires after the entire widget is rendered. Often used to trigger additional global scripts or plugins to run.
  • This function runs only once, when widget is first loaded on the page
  • Can be used with any of the widget template options (template, yearTemplate and itemTemplate)
  • This callback is not triggered by yearSelect or yearTrigger actions.
  • Can be used in conjunction with itemsComplete callback, but it will run after itemsComplete is finished.
Parameters
event Event
The event object.

Methods

reloadYears
A method to refresh the year list and content items after changing other widget options.
  • Method will re-render all items in the itemTemplate and yearTemplate.
  • This method can be triggered multiple times, but to avoid a loop it is recommended to trigger it only on a user's action (ex. click).
  • Note that this method will not work in conjunction with the template option.
  • Using this method instead of reloadItems will help to avoid showing unecessary years that do not have any content.
  • This method is usually used when combined with changing a widget option. See example 2 below.
Example
$('.events-widget').events('reloadYears');
Example
$('.sec-widget').sec('option', 'filingGroups', [1,3,4]);
$('.sec-widget').sec('reloadYears');
reloadItems
A method to refresh ONLY the content items after changing other widget options.
  • Method will re-render all items in the itemTemplate.
  • This method can be triggered multiple times, but to avoid a loop it is recommended to trigger it only on a user's action (ex. click).
  • Note that this method will not work in conjunction with the template option.
  • This method will be triggered automatically by setYear, setTags and reloadYears methods.
  • This method is usually only used when combined with changing a widget option. See example 2 below.
Example
$('.events-widget').events('reloadItems');
Example
$('.sec-widget').sec('option', 'filingGroups', [1,3,4]);
$('.sec-widget').sec('reloadItems');
setYear
A method to set the widget to only show content from a specific year, and trigger a reload of the content items.
  • Method will re-render all items in the itemTemplate.
  • This method can be triggered multiple times, but to avoid a loop it is recommended to trigger it only on a user's action (ex. click).
  • Note that this method will not work in conjunction with the template option.
  • This method will trigger the onYearChange callback.
  • This method will trigger the reloadItems method.
Parameters
year number
The year to display, or -1 for all years.
event Event
The triggering event, such as the user 'click'.
Example
$('.news-widget').news('setYear', 2018, e);
setTags
A method to set the widget to only show content from a specific year, and trigger a reload of the content items.
  • Method will set a tag filter for the widget, and reload the content based on that filter.
  • This method can be triggered multiple times, but to avoid a loop it is recommended to trigger it only on a user's action (ex. click).
  • Note that this method will not work in conjunction with the template option.
  • This method will either trigger the reloadYears or reloadItems methods, depending on parameters.
Parameters
tags Array.<string>
The array of tags to filter by.
reloadYears Boolean
Whether or not to reload the year list along with content items when setting a tag. When the tagTrigger/tagSelect options are defined, this parameter is true. If the parameter is set to true (or inherited to be true), the reloadYears will be triggered. If the parameter is set to false, the reloadItems will be triggered.
event Event
The triggering event, such as the user 'click'.
Example
$('.events-widget').events('setTags', ['featured'], e);