LiveWhale Support

Documentation»Widget and API settings

On this page

Widget and API Settings

Using widget settings (also known as “arguments” or args in LW code) you can select dynamic content from LiveWhale, filtering by group, tag, type, date, number, search keywords. There are also settings for how to format your results. Almost every widget setting is available as an API request, and vice versa.

Click the name of any linked setting below to see more detailed description and additional examples.

Learn more about LiveWhale Calendar widgets in the onboarding guide “Displaying Event Data on your Website.”

Common Settings

Name Description Accepted values Example Content types
fallback If no results, add/overwrite widget arguments one or more widget settings <arg id="fallback"><arg id="max_days">90</arg></arg> All
format The HTML markup for each widget result HTML and format variables <arg id="format">format<br/></arg> All
group Show items from group(s) string (“me” or any group name) <arg id="group">Biology</arg> All
header Header text string <arg id="header">My Widget</arg> All
hide_repeats Only show next instance of a repeating/multi-day event true/false/non_starred <arg id="hide_repeats">true</arg> Calendar Events
max Total number of items integer or “false” to show all <arg id="max">5</arg> All
only_starred Show only starred items true/false <arg id="only_starred">true</arg> All
sort_order Sort results by selected attribute varies by content type <arg id="sort_order">date</arg> All
start_date Starting date for widget items any relative or absolute date string <arg id="start_date">1/15/2024</arg> Events
tag Show items that are tagged with specific tag(s) string (any tag name) <arg id="tag">Soccer</arg> All

 

Calendar Settings

Some settings are used specifically for configuring the front-end calendar. Examples of these in action can be found in the setup user guide.

Name Description Accepted values Example Content types
ampm_with_dots Use “a.m./p.m.” instead of “am/pm” in time formats true/false <arg id="ampm_with_dots">true</arg> Calendar
category show items in selected category string (any category name) <arg id="category">lectures</arg> Calendar Events
category_mode require that items match any or all categories any/all <arg id="category_mode">any</arg> Calendar Events
default_view Which view should load first day, week, month, all, or home <arg id="default_view">month</arg> Calendar
disable_timezone Removes timezone abbreviations from all times (default: false) true/false <arg id="disable_timezone">true</arg> Calendar
display_all_day_events_last Show all day events at the end of the list rather than first (default: false) true/false <arg id="display_all_day_events_last">true</arg> Calendar
events_per_page Number of events to show in list view before “show more” (default: 50) Note: setting this higher than 50 is discouraged for performance reasons. integer <arg id="events_per_page">25</arg> Calendar
exclude_category do not show items in selected category string (any category name) <arg id="exclude_category">Deadlines</arg> Calendar Events
exclude_group Don’t show items from group(s) string (“me” or any group name) <arg id="exclude_group">Homepage</arg> All
exclude_tag Show items that are not tagged with specific tag(s) string (any tag name) <arg id="exclude_tag">Hockey</arg> All
exclude_view Don’t include this view in the menu day, week, month, all <arg id="exclude_view">month</arg> Calendar
exclusive_categories Only allow one category to be selected at a time (automatically pre-pends an “All” link) true/false <arg id="exclusive_categories">true</arg> Calendar
format_single_image Set the HTML markup of image when only one image is attached to an event (LiveWhale 2.8+ only, this overrides format_single_image from the default gallery) HTML and format variables <arg id="format_single_image">…</arg> Calendar
gallery_height Format the fullscreen gallery height when you have multiple images attached to an event (LiveWhale 2.8+ only, this overrides the image_height in the default gallery) integer <arg id="image_width">1000</arg> Calendar
gallery_width Format the fullscreen gallery width when you have multiple images attached to an event (LiveWhale 2.8+ only, this overrides the image_width in the default gallery) integer <arg id="image_width">1000</arg> Calendar
group Show items from group(s) string (“me” or any group name) <arg id="group">Biology</arg> All
hide_local_timezone Hide local times when user is outside the calendar’s timezone (default: false) true/false <arg id="hide_local_timezone">true</arg> Calendar
hide_repeats Only show next instance of a repeating/multi-day event true/false/non_starred <arg id="hide_repeats">true</arg> Calendar Events
home_view_combine_today_upcoming When using the home view, combine today’s featured events with upcoming featured events (max 10) into one list (default: false) true/false <arg id="home_view_combine_today_upcoming">true</arg> Calendar
image_height Format event details image height (in LiveWhale 2.8+, this overrides the thumb_height in the default gallery) integer <arg id="image_height">400</arg> Calendar
image_width Format event details image width (in LiveWhale 2.8+, this overrides the thumb_width in the default gallery) integer <arg id="image_width">600</arg> Calendar
location_char_limit Truncates the event location (default is 50 characters) integer <arg id="location_char_limit">60</arg> Calendar
month_view_day_limit Number of events shown in month view before “show X more…” link (default: 4) integer <arg id="month_view_day_limit">4</arg> Calendar
month_view_only Only show the month view true/false <arg id="month_view_only">true</arg> Calendar
search_all_events_only Any search will go to the “All” view (default: true) true/false <arg id="search_all_events_only">true</arg> Calendar
search_all_groups Any search will ignore settings for this calendar (default: false) Note: exclude_group settings will still be honored. We recommended this setting if your calendar homepage only shows one group. true/false <arg id="search_all_groups">true</arg> Calendar
show_archived Show archived items (default: false) true/false/both <arg id="show_archived">both</arg> Calendar Events News
show_categories Populates the category selectors for event type, audience, and campus true/false <arg id="show_categories">true</arg> Calendar
show_groups Populates with the group selector true/false <arg id="show_groups">true</arg> Calendar
show_locations Populates with the location selector true/false <arg id="show_locations">true</arg> Calendar
show_public Include events from the Public group true/false <arg id="show_public">true</arg> Calendar Events
show_tags Populates with the tag selector of starred, global tags applied to events true/false <arg id="show_tags">true</arg> Calendar
tag Show items that are tagged with specific tag(s) string (any tag name) <arg id="tag">Soccer</arg> All
tag_mode Require that items match any/all the specified tags (default: all) any/all <arg id="tag_mode">any</arg> All
thumb_height Format thumbnail image height integer <arg id="thumb_height">100</arg> All
thumb_width Format thumbnail image width integer <arg id="thumb_width">100</arg> All

All Settings

Basic

Name Description Accepted values Example Content types
center force map to center on specified coordinates <arg id="center">37.7528, -122.186</arg> Places
exclude_duplicates Remove results already displayed in earlier widgets on this page true/false <arg id="exclude_duplicates">true</arg> All
exclude_group Don’t show items from group(s) string (“me” or any group name) <arg id="exclude_group">Homepage</arg> All
group Show items from group(s) string (“me” or any group name) <arg id="group">Biology</arg> All
header Header text string <arg id="header">My Widget</arg> All
height <arg id="height">200</arg> Images Places
id display the following navigation, form, or gallery based on the provided id <arg id="id">1</arg> All
include_self On a details page, include the current item in widget results true/false <arg id="include_self">true</arg> All
max Total number of items integer or “false” to show all <arg id="max">5</arg> All
max_days How many days from the current date to display <arg id="max_days">10</arg> Events
min Minimum number of items, i.e., show no results if fewer than this integer or “false” to show in all cases <arg id="min">3</arg> All
paginate Display “Show more…” link after this many items are displayed(Note: when customizing a full calendar, use events_per_page) <arg id="paginate">25</arg> <arg id="paginate">false</arg> All
path directory path for images or file includes <arg id="path">/test/foo.php</arg> File Images
show_owner_only Show only posts made by the wall owner <arg id="show_owner_only">true</arg> Facebook
sort_order Sort results by selected attribute varies by content type <arg id="sort_order">date</arg> All
sort_search_results When true, your widget’s sort_order will apply even to results from a search argument (otherwise, the search argument always enforces sorting by search result relevancy) true/false <arg id="sort_search_results">true</arg> All
type Used for widgets that divide content by types <arg id="type">status</arg> <arg id="type">staff</arg> <arg id="type">mini</arg> <arg id="type">places</arg> All
url URL of a web feed <arg id="url">http://feed.com/feed.xml</arg> Feeds
user_id username for Facebook wall posts <arg id="user_id">username</arg> Facebook
use_widget select the widget(s) to combine <arg id="use_widget">1</arg> <arg id="use_widget">5</arg> Stream
width <arg id="width">100</arg> Images Places
zoom display map at specific zoom level <arg id="zoom">20</arg> Places

Categories

Name Description Accepted values Example Content types
category show items in selected category string (any category name) <arg id="category">lectures</arg> Calendar Events
category_mode require that items match any or all categories any/all <arg id="category_mode">any</arg> Calendar Events
exclude_category do not show items in selected category string (any category name) <arg id="exclude_category">Deadlines</arg> Calendar Events
use_category_classes apply categories as css classes true/false <arg id="use_category_classes">true</arg> Events News

Tags

Name Description Accepted values Example Content types
exclude_tag Show items that are not tagged with specific tag(s) string (any tag name) <arg id="exclude_tag">Hockey</arg> All
max_size maximum size (em) of scale range <arg id="max_size">2</arg> Tags
min_items minimum number of items that can appear in a tag cloud <arg id="min_items">1</arg> Tags
min_size minimum size (em) of scale range in tag cloud <arg id="min_size">.9</arg> Tags
tag Show items that are tagged with specific tag(s) string (any tag name) <arg id="tag">Soccer</arg> All
tag_list When true, returns a list of all tags; when false, the widget returns a cloud of only tags applied to live content <arg id="tag_list">true</arg> Tags
tag_mode Require that items match any/all the specified tags (default: all) any/all <arg id="tag_mode">any</arg> All
use_tag_classes Apply tags as CSS classes true/false <arg id="use_tag_classes">true</arg> All

Dates and Archives

Name Description Accepted values Example Content types
end_date Ending date for widget items any relative or absolute date string <arg id="end_date">9/17/2024</arg> All
show_archived Show archived items (default: false) true/false/both <arg id="show_archived">both</arg> Calendar Events News
start_date Starting date for widget items any relative or absolute date string <arg id="start_date">1/15/2024</arg> Events

Navigations and Breadcrumbs

Name Description Accepted values Example Content types
exclude_navigation exclude the selected navigation(s) <arg id="exclude_navigation">5</arg> Sitemap
from_group_nav display pages from a group’s navigation <arg id="from_group_nav">1</arg> Pages
from_nav display pages from a navigation <arg id="from_nav">1</arg> Pages
include_hidden include all menu items in HTML markup, including hidden items <arg id="include_hidden">true</arg> Navigation
include_separator_text Include separator text from navigation as breadcrumb links (default: false) true/false <arg id="include_separator_text">true</arg> Breadcrumb
is_section_navigation If current page is inside a section within the group’s main navigation, show that section navigation. If current page isn’t inside a section, don’t show anything. More info and examples. <arg id="is_section_navigation">true</arg> Navigation
levels Max # of nav levels to show in breadcrumb nav <arg id="levels">3</arg> Breadcrumb
main_nav Group’s main navigation to be associated with a breadcrumb nav <arg id="main_nav">academics</arg> Breadcrumb
navigation display only the selected navigation(s) <arg id="navigation">5</arg> Sitemap
nav_page Treat the specified page path as the current page when rendering a menu <arg id="nav_page">/path/to/my/page/</arg> Navigation
only_immediate_family Only include the current page’s immediate parent, siblings, and children in a navigation widget <arg id="only_immediate_family">true</arg> Navigation
separator Separator character <arg id="separator">*</arg> Breadcrumb
use_section_navigation If current page is inside a section within the group’s main navigation or the nav specified by ID, show that section navigation. If current page isn’t inside a section, fall back to showing the full navigation. (LiveWhale 2.10.7+) More info and examples. <arg id="use_section_navigation">true</arg> Navigation

Filtering and Sorting

Name Description Accepted values Example Content types
favorites display favorites for username(s) <arg id="favorites">username</arg> Twitter
filetype select the file type(s) to display <arg id="filetype">Document</arg> Files
filter select one of the options below with an action and a value to filter based on your criteria <arg id="filter" name="title" action="contains">Apples</arg> All
filter_mode require items match any/all filters below <arg id="filter_mode">any</arg> All
hide_repeats Only show next instance of a repeating/multi-day event true/false/non_starred <arg id="hide_repeats">true</arg> Calendar Events
host filter based on host(s) entered <arg id="host">www.localhost.com</arg> Pages
mention display feed for mention(s) <arg id="mention">mentions</arg> Twitter
only_starred Show only starred items true/false <arg id="only_starred">true</arg> All
only_today display only events occurring today <arg id="only_today">true</arg> Events
require_picture only show tweets with a picture <arg id="require_picture">true</arg> Twitter
search show items matching the search term <arg id="search">apples</arg> All
username display feed for username(s) <arg id="username">name</arg> Twitter

Format

Name Description Accepted values Example Content types
crop Crop all images to specified width/height true/false <arg id="crop">true</arg> Images
date_format display event dates in the specified format. <arg id="date_format">%F %j</arg> Blurbs Events News
date_format_header display date headers in the format <arg id="date_format_header">%F %j%S, %Y</arg> Events
excerpt_length limit feed content to a specific number of words <arg id="excerpt_length">5</arg> Feeds
facebook_suffix Add URL suffix for Facebook share links string <arg id="facebook_suffix">&foo=bar</arg> Save And Share
format The HTML markup for each widget result HTML and format variables <arg id="format">format<br/></arg> All
format_blurbs <arg id="format_blurbs"></arg> Places
format_events <arg id="format_events"></arg> Places
format_galleries <arg id="format_galleries"></arg> Places
format_images <arg id="format_images"></arg> Places
format_news <arg id="format_news"></arg> Places
format_places <arg id="format_places"></arg> Places
format_profiles <arg id="format_profiles"></arg> Places
format_starred format starred results with the selected attributes. <arg id="format_starred"><div class="lw_blurb_title">format_starred</div><div class="lw_blurb_body"></div></arg> All
header_block Which h# block gets wrapped around the header h2, h3, h4, or h5 <arg id="header_block">h2</arg> All
hide_date_headers hide date headers <arg id="hide_data_headers">true</arg> Events
ignore_cropper ignore custom thumbnail crops true All
min_image_size Exclude results with images that aren’t big enough to meet thumb_width/thumb_height? true/false <arg id="min_image_size">true</arg> All
script pull in custom scripts for galleries <arg id="script">/_assets/gallery-detail/slideshow.js</arg> All
shorten_urls Use shortened URLs in save and share links true/false <arg id="shorten_urls">false</arg> Save And Share
thumb_crop crop thumb images <arg id="thumb_crop">true</arg> All
thumb_height Format thumbnail image height integer <arg id="thumb_height">100</arg> All
thumb_width Format thumbnail image width integer <arg id="thumb_width">100</arg> All
time_format display event times in the format <arg id="date_time">%g%i %A</arg> Events
twitter_suffix Add URL suffix for Twitter/X share links <arg id="twitter_suffix">&foo=bar</arg> Save And Share

Advanced

Name Description Accepted values Example Content types
aggregate_markers aggregate markers when zoomed out <arg id="aggregate_markers">false</arg> Events Places
allow_indexing Force a widget’s output to be included in the search index for the page <arg id="allow_indexing">true</arg> All
class apply a custom class <arg id="class">your-custom-class</arg> All
columns display results across # of columns <arg id="columns">3</arg> All
disable_preview disable click to preview effect <arg id="disable_preview">true</arg> Images
extract Extracts content from the page element matching the specified id <arg id="extract">mission-statement</arg> File
extract_contents Excludes the wrapping container from a page element included with “extract” <arg id="extract_contents">true</arg> File
fallback If no results, add/overwrite widget arguments one or more widget settings <arg id="fallback"><arg id="max_days">90</arg></arg> All
include_javascript Load specified JS when this widget is used file path to JS or ES6 file <arg id="include_javascript">/_ingredients/extras/custom.js</arg> All
include_stylesheet Load specified CSS when this widget is used file path to CSS or LESS/SCSS file <arg id="include_stylesheet">/_ingredients/extras/custom.css</arg> All
is_remote Use cross-site urls for remote usage <arg id="is_remote">true</arg> Blurbs Files News Pages Profiles Tags
item_url location of template to use <arg id="item_url">/path/to/template.php</arg> All
list_order By default, columns are filled horizontally (1 in column A, 2 in column B, etc.), but you can now configure them to fill vertically (first half in column A, second half in column B). <arg id="list_order">vertical</arg> <arg id="list_order">horizontal</arg>
minutes caching the feed for specified minutes <arg id="minutes">30</arg> Facebook Twitter
my_related_content LiveWhale 2.14.0 and later: only show items that are attached to the current (or specified, by ID) item as related content (true/false/ID) <arg id="my_related_content">true</arg> All
my_related_content_type LiveWhale 2.14.0 and later: specify specific content type(s) to be pulled in by my_related_content (when true, inherit the type of the parent widget or details page) <arg id="my_related_content_type">news</arg> All
no_format disable automatic formatting/repair of included content <arg id="no_format">true</arg> File
no_results if no results—even after fallback, above—display a message (or another widget) <arg id="no_results">There are no results</arg> <arg id="no_results"></arg> All
related_to only show items that include the current item as related content (true/false) <arg id="related_to">true</arg> All
related_to_type LiveWhale 2.14.0 and later: specify specific content type(s) to be pulled in by related_to (when true, inherit the type of the parent widget or details page) <arg id="related_to_type">news</arg> All
require_image require attached image <arg id="require_image">true</arg> News Profiles
show_ical_link include a link to an iCAL feed of itemsavailable in: events <arg id="show_ical_link">true</arg> Feeds
show_public Include events from the Public group true/false <arg id="show_public">true</arg> Calendar Events
show_rss_link displays or hides rss link <arg id="show_rss_link">true</arg> All
show_tags show tag selector <arg id="show_tags">true</arg> <arg id="starred">true</arg> All
tags_header display a tag header <arg id="tags_header">Header</arg> All
until only show items until <arg id="until">09/30/2014</arg> <arg id="until"> + 2 week </arg> Feeds
wysiwyg_custom_widget_args Widget templates only: specify widget settings that users can override when inserting this widget array of widget settings <arg id="wysiwyg_custom_widget_args">header|max</arg> All