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).
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 inline gallery images places profiles |
show_owner_only | Show only posts made by the wall owner | <arg id="show_owner_only">true</arg> |
|
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> |
|
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 |
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 |
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 |
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 |
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> |
|
mention | display feed for mention(s) | <arg id="mention">mentions</arg> |
|
favorites | display favorites for username(s) | <arg id="favorites">username</arg> |
|
require_picture | only show tweets with a picture | <arg id="require_picture">true</arg> |
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) |
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 |
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 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 |
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 |
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 |
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 | <widget type="news"> |
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 | <widget type="news"> |
You can also inherit multiple arguments:
1 | <widget type="news"> |
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.
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}
.
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,
You could use this to divide up the results of a single widget by date:
1 | <h3>2019 Events</h3> |
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 | <div class="lwcw" data-options="id=123&format=html&group=Academic Calendar"></div> |
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:
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 | <div class="lwcw" data-options="id=123&format=html"></div> |
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 | <div class="lwcw" data-options="id=123&format=html"></div> |
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 | $_LW->REGISTERED_WIDGETS['profiles']['widget']['sort_fields'] = |
You can alter the above example to sort however you’d like.
Enter the content type (profiles, news, events, forms, galleries, etc):
$_LW->REGISTERED_WIDGETS[‘content type here’][‘widget’][‘sort_fields’].
Enter the label of the your sort method which will be shown in your widget editor drop-down menu (ex. ‘Custom Field: Year’)
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.
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']; |