Widget Arguments & Examples

Note: the below arguments apply to most widgets. See here for arguments specific to the calendar (i.e., the widget that creates the main view of your calendar).

Basic

Argument Description Examples Widgets
group Show items from group(s) <arg id="group">me</arg>​
<arg id="group">biology</arg>
all
exclude_group Don’t show items from group(s) <arg id="exclude_group">biology</arg> all
header Header (formatted as h3) <arg id="header">My Widget</arg> all
max Total number of items <arg id="max">10</arg> (most)
min Minimum number of items, i.e., show no results if fewer than this (LiveWhale 1.6.2+) <arg id="min">3</arg> (most)
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>
(most)
max_days How many days from the current date to display <arg id="max_days">10</arg> events
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>
blurbs
facebook
inline gallery
images
places
profiles
show_owner_only Show only posts made by the wall owner <arg id="show_owner_only">true</arg> facebook
main_nav Group’s main navigation to be associated with a breadcrumb nav <arg id="main_nav">academics</arg> breadcrumb
separator Separator character <arg id="separator">*</arg> breadcrumb
levels Max # of nav levels to show in breadcrumb nav <arg id="levels">3</arg> breadcrumb
user_id username for Facebook wall posts <arg id="user_id">username</arg> facebook
id display the following navigation, form, or gallery based on the provided id <arg id="id">1</arg> breadcrumb
inline form
inline gallery
navigation
url URL of a web feed <arg id="url">http://feed.com/feed.xml</arg> feeds
path directory path for images or file includes <arg id="path">/test/foo.php</arg> file
images
width <arg id="width">100</arg> images
places
height <arg id="height">200</arg> images
places
zoom display map at specific zoom level <arg id="zoom">20</arg> places
center force map to center on specified coordinates <arg id="center">37.7528, -122.186</arg> places
navigation display only the selected navigation(s) <arg id="navigation">5</arg> sitemap
exclude_navigation exclude the selected navigation(s) <arg id="exclude_navigation">5</arg> sitemap
use_widget select the widget(s) to combine <arg id="use_widget">1</arg>
<arg id="use_widget">5</arg>
stream
min_size minimum size (em) of scale range in tag cloud <arg id="min_size">.9</arg> tags
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
exclude_duplicates Remove results already displayed in earlier widgets on this page (LiveWhale 1.6.2+)
Note: ust be added to each widget to be tracked, and requires <arg id="paginate">false</arg>
<arg id="exclude_duplicates">true</arg> all
include_self When viewing the details page for a piece of content, that content will be excluded from widget results. You can set this to true to include it instead. (LiveWhale 1.6.2+) <arg id="include_self">true</arg> all

Dates and Archives

Argument Description Examples Widgets
start_date Starting date for widget items
Note: Various types of content entry are allowed. See other date examples here.
<arg id="start_date">09/10/2014</arg>
<arg id="start_date">10-09-2014</arg>
<arg id="start_date">-1 weeks</arg>
<arg id="start_date">monday this week</arg>
galleries
images
news
places
end_date Ending date for widget items <arg id="end_date">9/17/2014</arg>
See start_date for more formatting examples
galleries
images
news
places
show_archived show archived items <arg id="show_archived">true</arg>
<arg id="show_archived">false</arg>
<arg id="show_archived">both</arg>
news

Categories

Argument Description Examples Widgets
category show items in selected category <arg id="category">lectures</arg> events
exclude_category do not show items in selected category <arg id="exclude_category">Deadlines</arg> events
category_mode require that items match any or all categories <arg id="category_mode">any</arg> events
use_category_classes apply categories as css classes (LiveWhale 1.6+) <arg id="use_category_classes">true</arg> events
calendar

Tags

Argument Description Examples Widgets
tag show items that are tagged with specific tag(s) <arg id="tag">apples</arg> all
exclude_tag show items that are not tagged with specific tag(s) <arg id="exclude_tag">oranges</arg> all
tag_mode require that items match any/all the specified tags <arg id="tag_mode">any all
use_tag_classes apply tags as css classes <arg id="use_tag_classes">true</arg> all
tag_list
(LiveWhale 1.8+)
When true, <widget type="tags"> 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

Filtering and Sorting

Argument Description Examples Widgets
only_today display only events occurring today <arg id="only_today">true</arg> events
only_starred show only starred items <arg id="only_starred">true</arg> (most)
hide_repeats Only show next instance of a repeating/multi-day event. In LiveWhale 1.7.1+ “non_starred” hides repeats but shows them if the repeat is starred <arg id="hide_repeats">true</arg>
<arg id="hide_repeats">false</arg>
<arg id="hide_repeats">non_starred</arg>
events
search show items matching the search term <arg id="search">apples</arg> (most)
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) (2.5.0+) <arg id="sort_search_results">true</arg> (most)
filter_mode require items match any/all filters below <arg id="filter_mode">any</arg> (all)
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)
sort_order sort items by the following attributes (by default, sorting will start with balloons and then newest to top)
Oldest to top
Newest to top
Oldest to top (time only)
Newest to top (time only)
A-Z
Z-A
Popularity (google analytics)
Most tags matched, when matching multiple tags in tag_mode=any (1.6.2+)
<arg id="sort_order">date</arg>
<arg id="sort_order">reverse-date</arg>
<arg id="sort_order">time</arg>
<arg id="sort_order">reverse-time</arg>
<arg id="sort_order">alphabetical</arg>
<arg id="sort_order">reverse-alphabetical</arg>
<arg id="sort_order">random</arg>
<arg id="sort_order">most-tags-matched</arg>
all (options vary by widget type)
filetype select the file type(s) to display <arg id="filetype">Document</arg> files
host filter based on host(s) entered <arg id="host">www.localhost.com</arg> pages
from_nav display pages from a navigation (LiveWhale 1.6.2+) <arg id="from_nav">1</arg> pages
from_group_nav display pages from a group’s navigation (LiveWhale 1.6.2+) <arg id="from_group_nav">1</arg> pages
username display feed for username(s) <arg id="username">name</arg> twitter
mention display feed for mention(s) <arg id="mention">mentions</arg> twitter
favorites display favorites for username(s) <arg id="favorites">username</arg> twitter
require_picture only show tweets with a picture <arg id="require_picture">true</arg> twitter

Places

Argument Description Examples Widgets
has_location require location on map <arg id="has_location">true</arg> (most)
near_location show only items near coordinates or place ID <arg id="near_location">30</arg>
<arg id="near_location">37.7528, -122.186</arg>
(most)
near_distance show items within given number of miles <arg id="near_distance">10</arg> (most)

Format

​Argument Description Examples Widgets
hide_date_header hide date headers <arg id="hide_data_header">true</arg> events
thumb_width format thumb image width <arg id="thumb_width">100</arg> (most)
thumb_height format thumb image height <arg id="thumb_height">100</arg> (most)
thumb_crop crop thumb images <arg id="thumb_crop">true</arg> (most)
ignore_cropper ignore custom thumbnail crops <arg id="ignore_cropper">true (most)
date_format_header display date headers in the format <arg id="date_format_header">%F %j%S, %Y</arg> events
date_format display event dates in the specified format. <arg id="date_format">%F %j</arg> blurbs
events
news
time_format display event times in the format <arg id="date_time">%g%i %A</arg> events
format format results with the select attributes.
See Widget Formatting for details
<arg id="format">
<div class="lw_blurb_title">{title}</div>
<div class="lw_blurb_body">{body}</div></arg>
all
format_starred format starred results with the selected attributes. <arg id="format_starred">
<div class="lw_blurb_title">{title}</div>
<div class="lw_blurb_body">{body}</div>
</arg>
(most)
excerpt_length limit feed content to a specific number of words <arg id="excerpt_length">5</arg> feed
crop <arg id="crop">true</arg> images
src_region using a portion of the source image with coordinates in the format x,y,x2,y2 <arg id="src_region"></arg> images
feed
format_news <arg id="format_news"></arg> places
format_events <arg id="format_events"></arg> places
format_galleries <arg id="format_galleries"></arg> places
format_blurbs <arg id="format_blurbs"></arg> places
format_profiles <arg id="format_profiles"></arg> places
format_images <arg id="format_images"></arg> places
format_places <arg id="format_places"></arg> places
shorten_urls <arg id="shorten_urls">false</arg> save and share
facebook_suffix <arg id="facebook_suffix"></arg> save and share
twitter_suffix <arg id="twitter_suffix"></arg> save and share
google_suffix <arg id="google_suffix"></arg> save and share
script pull in custom scripts for galleries <arg id="script">/_assets/gallery-detail/slideshow.js</arg> galleries
stylesheet pull in custom styles for galleries <arg id="stylesheet">/_assets/gallery-detail/slideshow.css</arg> galleries

Advanced

Argument Description Examples Widgets
item_url location of template to use <arg id="item_url">/path/to/template.php</arg> galleries
news
places
profiles
​tags
show_rss_link displays or hides rss link <arg id="show_rss_link">true</arg> blurbs
feeds
galleries
news
profiles
show_ical_link include a link to an iCAL feed of items
available in: events
<arg id="show_ical_link">true</arg> feeds
related_to only show items related to the currently viewed event <arg id="related_to"></arg> galleries
news
profiles
columns display results across # of columns <arg id="columns">3</arg> blurbs
facebook
feeds
files
galleries
navigation
news
pages
profiles
stream
show_public include events from the Public group events
fallback if no results, add/overwrite arguments Expand date range:
<arg id="fallback"><arg id="max_days">90</arg></arg>

Unset all filters:
<arg id="fallback"><arg id="filter"></arg></arg>
all
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"><widget id="123_another_widget"/></arg>
blurbs
feeds
files
galleries
navigation
news
pages
places
profiles
stream
show_tags show tag selector <arg id="show_tags">true</arg>
<arg id="starred">true</arg>
blurbs
files
galleries
news
pages
profiles
stream
tags_header display a tag header <arg id="tags_header">Header</arg> files
galleries
news
profiles
class apply a custom class <arg id="class">your-custom-class</arg> all
require_image require attached image <arg id="require_image">true</arg> news
profiles
is_remote Use cross-site urls for remote usage <arg id="is_remote">true</arg> blurbs
files
news
pages
profiles
tags
slideshow apply slideshow effect <arg id="slideshow">true</arg> (most)
slideshow_interval slideshow interval in milliseconds to apply to effect <arg id="slideshow_interval">100</arg> (most)
slideshow_no_pausing disable slideshow pausing on mouseover <arg id="slideshow_no_pausing">true</arg> (most)
since only show items since <arg id="since">09/18/2014</arg>
<arg id="since"> -1 week </arg>
facebook
twitter
until only show items until <arg id="until">09/30/2014</arg>
<arg id="until"> + 2 week </arg>
feeds
minutes caching the feed for specified minutes <arg id="minutes">30</arg> facebook
twitter
extract extracts content from the page element matching the specified id (example) <arg id="extract">mission-statement</arg> file
pages
extract_contents excludes the wrapping container from a page element included with “extract” (example) <arg id="extract_contents">true</arg> file
no_format disable automatic formatting/repair of included content <arg id="no_format">true</arg> files
disable_preview disable click to preview effect <arg id="disable_preview">true</arg> images
include_hidden include all menu items in HTML markup, including hidden items <arg id="include_hidden">true</arg> navigation
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
aggregate_markers aggregate markers when zoomed out <arg id="aggregate_markers">false</arg> events
places
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>
most
allow_indexing force a widget’s output to be included in the search index for the page (LiveWhale 1.6.2+) <arg id="allow_indexing">true</arg> (most)
only_immediate_family Only include the current page’s immediate parent, siblings, and children in a navigation widget (LiveWhale 2.0+). More info and examples. <arg id="only_immediate_family">true</arg> navigation
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
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

Widget Argument Inheritance

Sometimes, you might put widgets inside widgets (widget Inception!). For instance, your format or format_widget arg may contain a whole other widget inside of it, or multiple widgets.

1
2
3
4
5
6
<widget type="news">
<arg id="format">
{headline}
Related content: <widget id="123"/>
</arg>
</widget>

In this example, if I apply a filter (say, a search or a tag argument) to my parent widget, I might also want the child widget to be filtered in the same way. Since LiveWhale 1.6.2+, I can use the “inherit” attribute on widgets inside format or format_widget to specify arguments that those children should inherit from the parent:

1
2
3
4
5
6
7
<widget type="news">
<arg id="tag">Admissions</arg>
<arg id="format">
{headline}
Related content: <widget id="123" inherit="tag"/>
</arg>
</widget>

You can also inherit multiple arguments:

1
2
3
4
5
6
7
8
<widget type="news">
<arg id="group">Admissions</arg>
<arg id="tag">Open House</arg>
<arg id="format">
{headline}
Related content: <widget id="123" inherit="group, tag"/>
</arg>
</widget>

You could, of course, accomplish this same thing by changing the inline widget settings, as in the examples above. Really, setting inherit will save you time when using it on a saved widget that will get reused in many places, potentially with many other criteria or filters that need accommodating.

Parent Widget Arguments

When creating a saved widget that will be used inside another widget’s results, you can reference the parent widget’s format variables by using the {parent_ prefix.

For instance, let’s say you have two profile types: Building and Room. You could have one widget for “List of all Buildings” and inside the results, use another widget <widget id="123_list_of_rooms"> to list the rooms inside each building. When setting up that second saved widget, use an argument like <arg id="tag" action="equals">{parent_title}</arg> to only return Room results that are tagged with the Building name. Or, you can reference a custom Building field like {parent_profile_99}.

Inline Widget Arguments (LiveWhale Calendar)

There’s no limit to the number of LiveWhale Calendar widgets you can create—however, there may be cases where you find it more efficient to re-use one saved widget rather than creating many copies. In those cases, you can alter certain criteria inline without having to make a whole new widget.

In your widget code, find the string that looks like data-options="id=123&format=html". You can add almost any event widget argument to that data-options string separated by ampersands. For example,

  • data-options=”id=123&format=html&group=Music
  • data-options=”id=123&format=html&category=Performances&exclude_tag=Private
  • data-options=”id=123&format=html&start_date=2020-01-01
  • data-options=”id=123&format=html&tag=soccer|hockey|basketball“ (use | to separate multiple values)

You could use this to divide up the results of a single widget by date:

1
2
3
4
<h3>2019 Events</h3>
<div class="lwcw" data-options="id=123&format=html&start_date=2019-01-01&end_date=2019-12-31"></div>
<h3>2018 Events</h3>
<div class="lwcw" data-options="id=123&format=html&start_date=2018-01-01&end_date=2018-12-31"></div>

Note: Use the date format YYYY-MM-DD when providing start_date and end_date to avoid ambiguity. More about start_date and end_date formatting here.

Or you can use one saved widget across many different pages and groups:

1
2
3
<div class="lwcw" data-options="id=123&format=html&group=Academic Calendar"></div>
<div class="lwcw" data-options="id=123&format=html&group=Biology"></div>
<div class="lwcw" data-options="id=123&format=html&group=Chemistry"></div>

Customizing your inline widget embed

Most customizations can be done on a per-widget basis, using the data-options customizations above. However, you can also make certain customizations on a per-embed basis. These are done by altering the <script> embed code:

Exclude stylesheets

By default, embedding a LiveWhale Calendar widget will also include the global theme’s widgets.css/less/scss stylesheet. However, you may wish to override this to not include any styles. You can do so by adding data-options="exclude_styles=1" to the script embed:

1
2
<div class="lwcw" data-options="id=123&format=html"></div>
<script type="text/javascript" id="lw_lwcw" data-options="exclude_styles=1" src="//calendar.mysite.edu/livewhale/theme/core/scripts/lwcw.js"></script>

Change the LiveURL directory

Most LiveWhale sites use /live as the LiveURL directory (i.e. the API endpoint). If your site is configured otherwise, you’ll need to specify the liveurl_dir in the settings:

1
2
<div class="lwcw" data-options="id=123&format=html"></div>
<script type="text/javascript" id="lw_lwcw" data-options="liveurl_dir=/my-api-endpoint" src="//calendar.mysite.edu/livewhale/theme/core/scripts/lwcw.js"></script>

Adding a custom widget sort method

While LiveWhale widgets come with a variety of sort methods, there are occasions when you’ll need a custom sort method to meet a specific need. To create a custom sort method for a LiveWhale widget, you’ll need SFTP access to your server and a reasonable knowledge of PHP and SQL.

Connect to your server via SFTP and locate your /livewhale/client/global.config.php in the LiveWhale back-end.

The following code adds a reverse sort for a custom profile field (ex., profiles_102).

1
2
$_LW->REGISTERED_WIDGETS['profiles']['widget']['sort_fields'] =
['Custom Field: Year' => 'profiles_102 DESC'];

You can alter the above example to sort however you’d like.

  1. Enter the content type (profiles, news, events, forms, galleries, etc):
    $_LW->REGISTERED_WIDGETS[‘content type here’][‘widget’][‘sort_fields’].

  2. Enter the label of the your sort method which will be shown in your widget editor drop-down menu (ex. ‘Custom Field: Year’)

  3. Enter the field to sort by and the sorting method (Desc, Asc) (ie, ‘profiles_102 DESC’) is the SQL sort that will be used to order the results.

  4. You can list secondary (or tertiary) sorting preferences, comma separated after the first, as in a typical SQL query SORT BY (e.g., profiles_102 DESC, profiles_103 – for built-in fields, use the table name, e.g., profiles_102 DESC, livewhale_profiles.title)

Once you’ve added the statement in your configuration file visit your widget editor for the matching widget type to make sure that the sort method appears and works as you intend.

Note: To add additional sorts to multiple widget types you’ll need a separate config statement for each.

Example: Sorting on a Date string (ex., ‘10/10/2020’) when the field is not a date type. The example below sorts on the year first, then the month, followed by the day. The SQL MID() function is used to extract characters from a text field.

1
​$_LW->REGISTERED_WIDGETS['profiles']['widget']['sort_fields']=['Exhibit Order Date' => 'MID(profiles_102,7,4) DESC, MID(profiles_102,1,2) DESC,  MID(profiles_102,4,2) DESC'];