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 using Localist Widgets.
Check out this Help Center article for more info:
Widgets Frequently Asked Questions
Table of Contents
Jump to section:
- Public Widget Builder
- Widget Builder Fields
- Display Options
- Generating Your Widget
- Custom Widget Templates
- Adding a Widget Template
- Other Widget Templates
- Widget Parameters
- Filter Parameters
- Feature Face-Off: Widgets vs. API
Public Widget Builder
The public 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:
|
| 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.
|
| Style | Localist provides three out-of-the-box styles to choose from:
|
| 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.
|
| 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.
|
| Badge | This creates a See More Events button that can be added to any webpage or as a compliment to a widget event list.
|
| _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:
|
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:
|
array (string) | small |
| show_keywords | show Keywords assigned 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 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:
- Are you looking to integrate Localist content into another system’s internal interface? If yes, then you will need to use the API.
- 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.
|
- HEADS UP - Here are some helpful troubleshooting tips to try before you reach out to the support team
|