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.

Frequently Asked Questions

Who can create Widgets?

Any public site visitor can make a Widget — this means that your events can be promoted all over the web! For example, another department within your organization or a community partner can make a Widget of your events for their sites, which will ultimately drive traffic back to your calendar.

What is a Widget vs a Widget template?

Templates are the various Widget designs from which you can select in the Widget builder. While Widgets are the actual display of your events on another page.

Can I sort by Widget by Trending?

Once you’ve generated your Widget URL, you can add &sort=ranking to indicate that the Widget should sort events by the Trending algorithm.

Can I create a past events Widget?

You can have a rolling past events Widget — i.e. “the last 30 days”. For example, once you’ve generated your Widget URL you can replace the days parameter with &days=-30 to indicate that the Widget should pull events from the previous 30 days.

Why is the Localist logo only displaying, but no event content?

Most likely, the reason the Widget is not displaying on the website because of SSL protocol alignment issues. For context, SSL refers to when a website offers encryption, which is noted in the URL using https (secure) vs http (non-secure). When it comes to embedding content, you can embed content using https (like a Widget) on a non-secure/http page, but you cannot do the reverse and embed content using http on a secure/https page. This is often called upgrading security (allowed: posting https on an http site) or downgrading security (not allowed: posting http on an https site).

The Widget Builder

The Widget Builder can be accessed by navigating to Content > Widgets > Public Widget Builder or by default it is publicly linked in the homepage’s Share Events box.

Widget Builder Fields

Field Details
Template Select the default template or one of your custom Widget templates.
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).
Places Select all that apply.
Filters Select all that apply.
Keywords and Tags Enter all applicable words.
Show Only Featured When checked, only events flagged as a Featured Event will be included.
Show Only 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.
Hide Past Events Hide all events in the past.
Content Must Match Select one of the following:

  • 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 Widget. This is helpful in an “all, but one” situation.

Display Options

Field Details
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 Type Filters to narrow down what events the list displays. The mini cal and “today’s events”/”this week’s events” will change the list results accordingly. The mini calendar extends 12 months.
Style Localist provides three out-of-the-box styles to choose from:

  • Modern
  • Card
  • Classic
Hide Descriptions Event descriptions will not be shown.
Truncate Descriptions Description, location, and event image will be hidden upon page load, however, 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.
Hide ‘View All Events’ Link The view all events link 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.

Field Details
Preview Widget This 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.
Generate Embed Code This will display the embed code for your Widget to be included on your website.

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

  • Navigate to Content > Widgets
  • Select +Add Widget Template
  • 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, Classic, and Card:
  • Save Changes

Other Widget Templates

In Content > Widgets you’ll automatically see your Widget theme templates (Classic, Modern, Card, & Mini Calendar + List) along with the following:

Field Details
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 Interested” on. User 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 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 parameter (example: venues[]=1&venues[]=2 )
    • Comma separated values (venues=1,2 )
  • 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 number 10
days number of days in the future (1-365)
HEADS UP: If you’d like to create a past events Widget, you’ll add – to indicate how many days in the past you’d like to pull from. For example, days=-30.		 number 7
start date the Widget should start (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 array none
departments only return events assigned to these Departments array none
skip_recurring do not include recurring events boolean FALSE
all_instances show all instances of recurring events (instead of only the next instance) boolean FALSE
picks only include events flagged as Featured boolean FALSE
sponsored only include events flagged 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/Filters:

  • Not set (default): matches events that have at least one of the listed Tags/Filters.
  • All: matches events that have all listed Tags/Filters.
  • Any: matches events that have at least one of the listed Tags/Filters
 array (string) none
sort sort events by the ‘Trending’ algorithm array chronological

Output Parameters

Parameter Description Type Default
hidedesc hide descriptions boolean FALSE
hideimage hide images boolean FALSE
image_size returns:

  • tiny (20×20)
  • small (50×50)
  • medium (80×80)
  • big (200×150)
  • big_300 (300×225)
 array (string) small
show_keywords show Keywords assigned to events boolean FALSE
show_times shoe event start times boolean TRUE
show_year show the year of the event date boolean FALSE
show_types show Event Type Filters below the event description boolean FALSE
style suppress default style array (string) none
target_blank opens 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

Feature Face-Off: Widgets vs. API

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.

– HEADS UP –

Here are some helpful troubleshooting tips to try before you reach out to the support team!

 

  • Widget is not displaying on the page: You will need to check the Widget’s URL — if you have SSL on your platform the URL should display ‘https’ and not ‘http’.
  • Event is not being included in a Widget: Check the Classification, date range, number of Events, & that all is content matching.
  • Widget is not displaying like the preview: The CSS on the page may be altering the Widget, so you’ll need to change the CSS on the containing page.

Was this article helpful?