Widget basics

Because widgets are such versatile and useful tools in LiveWhale, it was impossible to find a name for them that accurately reflected what they are and can do. So “widget” was the best we could do.

But seriously, believe us, widgets are awesome.

What’s a widget?

The markup shown here is how widgets work on the LiveWhale platform. This means that if you’re creating content on your calendar server (which is powered by LiveWhale), you can use this syntax.  If you’re using widgets on another platform, CMS, etc, the syntax is a little different; we’ll cover that below.

In LiveWhale, a widget is a little bit of XML code that puts some calendar (or CMS) content on a webpage.  On a LiveWhale-powered webpage, the simplest widget possible looks like this:

<widget type="events"/>

If you load a LiveWhale-powered page containing that widget, you’ll see a list of all the events in the database for that site, with a range of default settings for how they’re presented, how many show up at a time, etc.

You can add more specific instructions to a widget using “arguments,” via the <arg> tag, with a very wide range of possibilities. Here’s a widget that returns only events tagged “festival,” from the Campus Life group:

The markup shown here is how widgets work on the LiveWhale platform. This means that if you’re creating content on your calendar server (which is powered by LiveWhale), you can use this syntax.  If you’re using widgets on another platform, CMS, etc, the syntax is different; we’ll cover that below.

<widget type="events">
  <arg id="tag">festival</arg>
  <arg id="group">Campus Life</arg>
</widget>

 You get the idea. 

Why would you use one?

The most common use of a LiveWhale Calendar widget is to put a list of upcoming events on a webpage. In fact, for most LWC uses, “widget” and “event list” are interchangeable terms, although there’s way more you can do with widgets.

The default widget (DW)

When you install LiveWhale Calendar, there’s a single widget that comes included: the “default widget” or “basic” events widget (DW for short).  This is a saved widget that displays a standard list of events, with some default formatting. 

You can customize anything about the DW, from the HTML markup that it generates for event lists to the number of events that are displayed at a time.  And when you place the DW on a page, you can add page-specific arguments to return the exact events you want to display.

Deploying the default widget

Because the widget is saved in LiveWhale Calendar, you can deploy it on a webpage without making reference to the specific details (i.e. arguments) of the widget itself.  Your DW has the id of 1, and in LiveWhale syntax, you’d put it on a webpage like this:

<widget id="1"/>

Most LiveWhale Calendar customers will be placing widgets on webpages that aren’t powered by the LiveWhale platform but by a different CMS.  This means you’ll be using a Javascript version of this widget; the syntax is different, but everything else is the same.  Here’s how you’d place the DW from demo.lwcal.com on a webpage:

<div class="lwcw" data-options="id=1&format=html"></div> 

<script type="text/javascript" id="lw_lwcw" src="http://demo.lwcal.com/livewhale/theme/core/scripts/lwcw.js"></script>

The first block above is the widget itself; that code requests widget #1 from a LiveWhale Calendar server.

We aren’t always going to include this <script> tag when we talk about the JS widget, but just remember that any LWC Javascript widget needs it somewhere in the page to work.

The second block calls some Javascript that tells the widget where to look and how to work; it can be included with the widget, or loaded elsewhere on your webpage (for example, in a sitewide header include).

Customizing the default widget

Customizing the DW is largely a matter of adding arguments to it. You can add these arguments to the saved version of the DW; then they’ll apply to every instance of the widget that you use. Or you can apply them on a widget by widget level, setting specific rules for specific widgets on your webpages. Most likely you’ll do a combination of both.

Editing the DW
To view your list of widgets, select “Widgets” from the toolbox dropdown menu. (It’s only visible to users at the “curator” level and above.) You’ll see your default events widget there; click to edit it. (The widget edit screen, and the many options it offers, is discussed in the next section.) The changes you make will be saved as part of the DW, and all the widgets you’ve deployed will reflect your changes.

Adding widget-specific arguments
When you’re placing a widget on a page, usually you’ll be looking for something different than a list of all the events in your calendar; most commonly you’ll be limiting the display of events by group, event type, or tag.

The widget syntax for specific args is very simple. Here’s a sample DW that displays events from the Music group, with the event type Performances, tagged either “orchestra” or “chamber orchestra.”

Native LiveWhale widget syntax:

<widget id="1">
   <arg id="group">Music</arg>
   <arg id="category">Performances</arg>
   <arg id="tag">orchestra</arg>
   <arg id="tag">chamber orchestra</arg>
   <arg id="tag_mode">any</arg>
</widget>

<div class="lwcw" data-options="id=1&groups=Music&categories=Performances&tags=orchestra,chamber orchestra&tag_mode=any"></div> 

(Of course, this version of the widget still requires the link to the Javascript file telling it what to do, mentioned above.)

Creating new widgets

You can create new widgets (and edit existing ones) from the Widgets page, which admins can access in the Toolbox:

Here’s the basic widget editor interface.

There’s a title and description; a live preview of your widget, which changes as you modify options; and the generated widget syntax, which shows the arguments you’re adding to the widget as you select options. Then the options themselves can be toggled between Simple options (which is all most end users will need) and All options (which is a somewhat overwhelmingly long list of every possible widget option under the sun).

There are a LOT of options that you can manage with widgets. Each of these options corresponds to a widget argument; as discussed above, you can save these arguments as part of the widget itself, or add them later when placing the widget on a page. 

Simple options

We like to think these are pretty self-explanatory! When you enter values for these options, it modifies the widget you’re working on. You’ll see the widget syntax update as you go, and the preview will update when your changes affect the widget’s output.

When you’re done making changes, save your widget. Then you can grab the widget embed code from the widget manager page, using the “Get Code” link:

(If your CMS requires a different style for this embed code, it can be customized to match your needs.)

The “Simple options” are designed to be all your calendar managers need to create great event feeds for their webpages. “All options” is where things get interesting (or intimidating, depend on how you feel about user interfaces).

All widget options

There are a LOT of these. Gosh.

I mean, we warned you, right? You can click the image at right to open it at full size in a new window.

Note that not all these options are relevant for widgets embedded using the Javascript method.

Frankly, if you’re a developer, you will love the wide variety of options available here. We’ll cover the most important and frequently used of them here; we encourage you to get in and explore the rest. 

Groups
You can limit the output of a widget to events from one or more groups, and/or exclude groups from the widget. The former is widely used, especially as a widget-specific argument added when a widget is placed; the latter can be useful if you’re looking for a broad and diverse list of events but want to exclude groups whose events are only for internal use.

Dates
You can set before and after dates for showing events.  These fields have date pickers for precise date ranges; however, you can also enter relative values. So a value of +7 days for “after” and +14 days for “before” will return a list of events starting a week from today.

Event types (“categories”) and tags
An advanced option here is “tag” or “category mode”— if your widget calls for more than one event type or tag, you can pull events matching all or any of them. (“All” is the default option.) 

Filtering & sorting
There are many options for filtering and sorting events; you can pull only starred events, only events happening today, only events in English, and so forth. You can even pull all events matching any search keyword, or filter your events by any of its data attributes.

Places
You can limit an event list by location— say, only showing events within 5 miles of New York City.

Format
(This section we’ll talk about in great detail below.)

Advanced
This section is something of a grab bag of legacy and marginal options that are used in rare cases by LWC developers. 

Custom widget formatting

The most important way that you can customize a widget— especially the default widget that you’ll be using in lots of different places— is in its formatting. You can format the output of a LiveWhale Calendar events widget in any way you need— to match your site’s existing styles, the markup style of your CMS, or even in another markup language like XML or XSLT.

We’ll go through each of these in brief, and the most important (“format”) in detail.

Hide date headers
By default widgets include the date before each day’s events in a list. You can turn that off here.

Include empty days?
Days without any events don’t display date headers, unless you turn this off. (It can be useful if you’re making a calendar-like layout where you’d like to show empty days.)

Thumbnail width and height
These are set by default in your main configuration file, but can be adjusted for specific widgets here.

Crop thumbnails?
If you set this to “No,” your thumbnail will be stretched to meet these dimensions.  (Probably just leave this one alone.)

Ignore thumbnail crops?
You can crop a thumbnail to a specific region when editing an event. Choosing “Yes” here ignores that (and is best when you’re generating non-square thumbnails).

Date, time, and date header format
Customize the format of the time using PHP syntax; this reference will be indispensable if you do customize your date formats.

The format argument

The large text area here contains the markup that the calendar will output for each event in your widget.  You can write any markup here that you want, and include the event variables in {curly brackets}.  

All the event variables can be added by clicking the shortcut links under that box— date, time, description, and so forth. 

For a simple example, if you wanted your event list to look like this:

Office Christmas Party

December 5th, 2017
8:00pm
Tagged: super fun, good times

Lunch with Santa

December 8th, 2017
12:00pm

…. then you’d be looking for markup similar to this:

<h4>Office Christmas Party</h4>
<p class="date">
   December 5th, 2017<br/>
   8:00pm<br/>
   Tagged: <em>super fun, good times</em>
</p>
<h4>Lunch with Santa</h4>
<p class="date">
   December 8th, 2017<br/>
   12:00pm
</p>

… which means your format argument would look like this:

<h4>{title}</h4>
<p class="date">{date}<br/>
{time}<br/>
{Tagged: |tags|}
</p>

Simple, right?

Extra special top secret feature alert bonus: As you can see with the “Tagged:” section, there’s syntax for showing content only if a variable exists:

{ Only output this content if |this-variable| exists.}

Wrapping widget output in markup

It’s often sensible to output content as an unordered list.  To do this, wrap your widget format in <li>, then use the “Wrap widget output with markup” option to include the markup that should come before and after your widget:

<ul>
   {widget}
</ul>

This can also be useful when you’re outputting content to work in a jQuery plugin (like a gallery/slideshow, for example), and need a wrapper around your markup.

One more note for good measure
Some format variables come with their own markup; {title} and {tags} are generated as links, for example. For most variables you can ensure a plain-text-only output by adding _clean to the end of the variable.  So in the example above, if you didn’t want the event titles or tags to be linked, your format would look like this:

<h4>{title_clean}</h4>
<p class="date">{date}<br/>
{time}<br/>
{Tagged: |tags_clean|}
</p>

Widgets in your CMS

Content TBA

Advanced widgetology

Content TBA