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

Dates and Archives

Categories

Tags

Filtering and Sorting

Places

Format

Advanced

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'];