Home

Widgets

A widget enables you to create events once in Localist and publish everywhere with Widgets. Administrators and users can embed and display events or series of events on pages separate from the main calendar, such as the organization’s website homepage, partner organizations websites or other pages.


In this article you’ll find:

  • The Widget Builder
  • Style Options
  • Customizing Widget Templates
  • Widget Parameters
  • API vs Widgets
  • FAQ

The Widget Builder

Navigate to Content > Widgets

 

Widget Builder Fields

  • Number of Results: You can enter any number up to 50.
  • Days Ahead:  You can enter any number up to 365.
  • Groups/Departments:  The builder allows you to select one group. If you’d like to pull multiple groups’ or departments’ events you can tack on more groups or departments to the URL (&groups=group_a&groups=group_b OR &departments=department_a&departments=department_b). It’s just not currently baked into the actual builder.
  • Keywords and Tags:  Enter all applicable words.
    • Note:  this is only available to admins.
  • Only Show Featured:  When checked, only events flagged as a featured event will be included.
  • Only Show Sponsored:  When checked, only events flagged as a sponsored will be included.
  • Include All Matching Instances:  If checked, the widget will display all recurring instances. If not checked, the widget will only display the first instance in the recurring chain.
  • Places:  Select all that apply.
  • Filters:  Select all that apply.
  • Content Must Match
    • At least one place, group keyword or tag, and one filter item
    • Any place, group, keyword, tag, or filter item
    • At least one place and group, and all keywords, tags, and filter items
    • Any place or group, and at least one keyword or tag, and one filter item
  • Excluded Content:  Any filters specified in these drop downs will not be included in the widgets. This is helpful in an “all, but one” situation.
  • Hide past events

 

 

Display Options

  • Widget Type:  You have the option of a List Widget or a Mini Cal + List Widget.

The List + Mini Cal Widget provides a drop down of all available event filters to narrow down what events the list displays and the mini cal and “today’s events”/”this week’s events” will change the list results accordingly. The mini calendar extends 12 months. 

 

Widget Style: Classic

 

Widget Style: Modern

 

Mini Cal + List: 

 

 

The Card style cannot be paired with the Mini Calendar + List widget type:

 

 

Hide Descriptions:  Event descriptions will not be shown.

Truncate Descriptions:  Description, location, and event image will be hidden upon page load, but when an event is clicked this information will appear.

Render HTML in Descriptions:  This allows any HTML entered in admin (bold, etc.) to be displayed automatically.

Hide Event Images:  Photos will be completely hidden.

Hide Event Times:  Times will be completely hidden.

Open Links in New Window:  If an event is selected, another window will open.

 

Generating Your Widget

After you have made all necessary specifications, you will see two options to generate your widget results. Note:  No saving is required.

The first option, Preview Widget, will open your widget results in another tab. On this page you can confirm that the correct events are showing and that the output options are working as expected.

After you have previewed your widget and confirmed that the results are correct, select Generate Embed Code. Selecting this will display the embed code for your widget to be included on your website page.

 

 

Custom Widget Templates

Localist allows you to create widgets with custom code that changes the overall look, feel, and behavior of Localist’s standard widgets. You can use this tool to build widgets that match the aesthetic of your homepage, a sub-page, or a separate website.

 

Adding a Widget Template

1. Navigate to Content > Widgets

2. In the editor screen select the template you want to edit

OR

1. Click +Add Widget Template 

2. Name your widget and choose which template to copy from as a starting point.

  • Display Name:  This is what will be displayed in the public facing widget builder’s style drop down.
  • Internal Name:  This will be automatically filled in. For example, if you enter “Pinterest Board” for the Display Name then the Internal Name will be pinterest-board. This is displayed in the URL the widget builder generates when using a custom theme.
  • Copy From:  This allows you to pick another default or custom widget’s HTML to build off of. The Defaults are Modern and Classic:

3. Save Changes

 

 

Places List:  This displays a list of place profiles with name, image and description in the List (Classic) style.

  • Generating a preview:  Visit yourcustomdomain.com/widget/places?format=html.
  • Creating a script tag:  <script src=yourcustomdomain.com/widget/places></script>
  • Filtering
    • You can pull places with a certain type by adding types[]=1234 (ID is found in the admin URL)
    • Restrict the list amount by adding num=5
    • Sort list in alphabetical order by adding order=name

 

 

Logged-In User Plans:  This displays a list of events that a user has selected “I’m Going” on (Note: they must be currently logged in).

  • Generating a preview:  Visit yourcustomdomain.com/widget/plans?format=html.
  • Creating a script tag:  <script src=yourcustomdomain.com/widget/plans></script

 

 

Badge:  This creates a See More Events button that can be added to any webpage or as a compliment to a widget event list.

  • Generating a preview:  Visit yourcustomdomain.com/widget/badge?format=html.
  • Creating a script tag:  <script src=yourcustomdomain.com/widget/badge></script

 

 

_platform_styles:  This file affects the List (Classic), Logged-In User Plans and Place List widgets.

 

 

Widget Parameters

These are some additional parameters that can be used for the widget, in addition to those available on the widget builder.

Parameter Details

Each parameter should be passed in as standard parameter in the widget URL.

Parameters marked as array can be specified as array parameters (example: venues[]=1&venues[]=2) or comma separated values (venues=1,2). The two forms cannot be mixed.

Boolean parameters are true for values of 1, y, yes, true. In many cases, the presence of the parameter is all that is required. (When in doubt, don’t include false parameters).

Filter Parameters

Parameter Description Type Default
num number of events to return (1-50) number 10
days number of days in the future to look at (1-365) number 7
start date that the widget should start from (YYYY-MM-DD) date today
venues only return events at these venues (ID or username) array none
school only return events assigned to these schools (ID or username) array platform specific
campuses only return events assigned to these campuses (ID or username) array platform specific
groups only return events assigned to these groups (ID or username) array none
skip_recurring do not include recurring events boolean FALSE
all_instances show all instances of recurring events (instead of only the next) boolean FALSE
picks only include featured events boolean FALSE
sponsored only include events marked as “sponsored” boolean FALSE
tags return events with any of these tags or keywords array (string) none
types return events with any of these filter values array (type ID) none
exclude_types exclude events matching these filter values array (type ID) none
match_all controls matching requirements for tags/types>When not set (default), matches events that have a least one of the listed tags or types> When all, matches events that have all listed tags and types> When any, matches events that have at least one of the list tags and types string none

 

Output Parameters

Parameter Description Type Default
hidedesc hide descriptions boolean FALSE
hideimage hide images boolean FALSE
image_size return tiny 20×20, small50x50, medium 80×80, big 200×150, big_300 300×225 string small
show_keywords show keywords assign to events boolean FALSE
show_times show event start times boolean TRUE
show_year show the year of the event date boolean FALSE
show_types show event types below the event description boolean FALSE
style suppress default style string none
target_blank open event and venue links in a new window boolean none
html_descriptions output the raw HTML in event descriptions boolean FALSE
format=rss convert to RSS feed html
 

API vs. Widgets

If you’re evaluating whether to use the Localist API or Localist Widgets to spread event content outside of Localist, first ask yourself 2 questions:

  1. Are you looking to integrate Localist content into another system’s internal interface? If yes, then you will need to use the API.
  2. Do you have the technical expertise or resources to build and implement a tool that displays JSON data on a web page? If no, then you will need to use a widget.

Outside of these two scenarios, the choice between the API and widget depends on your preferences. That said, we recommend always using the widget builder if you are only looking to display content on other pages as it’s quicker and generates styled data.

 

Key Differences

API

  • Requires technical knowledge of JSON
  • Raw JSON data
  • Customer is responsible for building and implementing a tool that displays API data
  • Customer is responsible for building and implementing the HTML (etc.) presentation
  • Designed to show impeccably up-to-date data with slower, cached load times
  • Can be used to integrate internally with other systems (i.e, importing data into a CMS)
  • Flexible querying: http://www.localist.com/doc/api
  • Long time commitment

Widget

  • Requires only a very basic understanding of editing web pages in a CMS
  • Formatted data
  • Prebuilt component that is added to a page with Localist provided embed codes
  • Localist provided HTML presentation available
  • Designed to load quickly, but does not show exact up-to-date data
  • Can only be used for displaying content on a page (i.e, displaying data on a CMS page)
  • Limited parameters: see above
  • Short time commitment

 

FAQ: Widgets

Q:  HOW CAN I REMOVE THE “POWERED BY LOCALIST” MENTION IN THE WIDGET?

A:  After you have built your widget, select “generate embed code.” The code will look like this:

<script type=”text/javascript”
src=”http://calendar.clemson.edu/widget/view?schools=clemson&days=31&num=50″></script><div id=”lclst_widget_footer”><a rel=”nofollow” style=”margin-left:auto;margin-right:auto;display:block;width:81px;margin-top:10px;” title=”Widget powered by Localist Online Calendar Software” href=”http://www.localist.com?utm_source=widget&utm_campaign=widget_footer&utm_medium=branded%20link”><img src=”//d3e1o4bcbhmj8g.cloudfront.net/assets/platforms/default/about/widget_footer.png” alt=”Localist Online Calendar Software” style=”vertical-align: middle;” width=”81″ height=”23″></a></div>

Remove the bolded code.

 

Q:  HOW CAN I HIDE AN EVENT FROM THE MAIN CALENDAR, BUT STILL HAVE IT AVAILABLE IN A WIDGET?

A:  Restrict the visibility to Widget on the event form.

 

Q:  HOW DO I SHOW PAST EVENTS IN A WIDGET?

A:  Set the “start” parameter to 01-01-2018 and set the number of days = 365. This will enable the widget to include past events as well as future event listings.

 

Q:  CAN I EXCLUDE EVENTS THAT DON’T HAVE AN EVENT TYPE FROM THE WIDGET?

A:  No, in order to exclude classes from being included they will need a specific filter, tag, or keyword that is marked as “excluded” using that parameter for the widget.

 

Q:  IS IT POSSIBLE TO CREATE A MINI CAL-ONLY WIDGET SO THAT WHEN A DATE IS SELECTED THE USER IS TAKEN TO THE MAIN CALENDAR PAGE FOR THAT DAY?

A:  This is not possible as the mini cal is built as a navigation tool specifically for the widget so the links can only connect to a list of corresponding events for each day on that page. However, if an event title is selected then a user will be taken to the event’s details page on the main calendar.