Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 10 Next »

This documentation describes how to create and maintain list widgets in Pika.


Table of Contents

What are List Widgets?

The basic idea of a List Widget is to embed a search or list from Pika on your library homepage for display. List widgets are a seamless way to display targeted content from the catalog on your website and direct patrons to titles in the catalog directly from your library website.

Screenshot of a list widget from a library website homepage

Widgets embedded on webpages always display starting somewhere in the middle of their respective sources (list or search) rather than at the very beginning/left hand side. This is by design so the results don’t appear empty on webpages.

Top of page

Getting started

In order to create the List Widget, you must be signed in. Your account must have a user role of library admin or content editor. A content editor has permissions to create List Widgets, editorial reviews and Browse Categories.  

Once you’re logged in, click on the List Widget link under the Pika Configuration tab.

Screenshot of the pika configuration menu highlighting the list widgets menu option


Click on the Add New List Widget button to create a new widget. 

You can also find a widget you have already created by narrowing down the search by Id, Library, or Name.  You can edit existing widgets by clicking on the Edit link under Actions.

Screenshot of the list widgets table highlighting the add new list widget button, the search and sort options, and the edit access link

Top of page

Creating a widget and widget options

Click on the Add New List Widget button to create a new list widget. 

Library

Library is a dropdown menu that limits the availability of the widget. Choose your library in this field. When a specific library is assigned, only admin patrons at your library will be able to edit the widget. 

If the widget can be used by all libraries, set the library value to All Libraries. (This is not a common setting)

Name

Name is the title of your widget.

Screenshot of the library menu and the name field

Show the list widget’s title bar

If the Show the list widget’s title bar option is enabled, the text from the Name field for the widget will display in the bar if the widget only has a single tab. If there is more than one tab in the widget, the Name will not display in the title bar.

Screenshot of the show the list widget title bar option

Here is an example of the Show the list widget’s title bar

Screenshot of a list widget highlighting the name in the title bar

Show view more

Show the View More link on the title bar of the widget controls where the View More link is shown. When a user clicks on the View More link in a widget, they will be directed to the search results or list that is the source for the widget

Screenshot of the view more option

Here is an example of the View More link that shows up when the Show the View More Link on the title bar of the widget is checked.  

Screenshot of a widget highlighting the view more link

Display mode for search results

Display mode for search results link is used to show full search results when the View More link option is enabled and the source for the widget is search results.

Screenshot of the display mode for search results link option

Description

Description is for internal use.  You can copy and paste any search strings used to create the widget or the list ID if you’re using a list for a source.

Screenshot of the description field

Should description pop-up


Should the description pop-up be shown when hovering over titles? Is used when you want to have a description show when someone hovers over a title.

Screenshot of the should description popup option

Number of titles display

The number of titles that should be shown for the widget option is used to limit the amount of titles that display in the widget. The default value is 25 and likely should not be changed, especially if the search results that are referenced are quite large

Screenshot of the number of titles display option

Title information display options

There are three settings that can be chosen to show information about the titles in your widget.

  • Should the title for the currently selected item be shown?

  • Should the author (catalog items) /format (archive items) for the currently selected item be shown?

  • Should ratings widgets be shown under each cover?

All three options can be enabled in conjunction with one another, you can enable a single option, or you can enable a combination of any two options.

If both title and author name are enabled or all three options are enabled, you will need to adjust the height of the widget in the iframe to accommodate the auto-rotation option.

Should the title for the currently selected item be shown

When this option is enabled, the title will display under the cover art in the carousel.

Here is an example of a widget that has the title listed under the item, as well as one without the title.

Screenshot of a title in a widget with the title display
Screenshot of a title in a widget without the title display

Should the author (catalog items)/format (archive items) for the currently selected item be shown

This setting determines if the author’s name is displayed under the item.

Here is an example of a widget that has the author listed under the item, as well as one without the author.

Screenshot of a title in a widget with the author display
Screenshot of a title in a widget without the author display

Should ratings widgets be shown under each cover

This setting determines if the rating is displayed under the item.

Here is an example of a widget that has the ratings listed under the item, as well as one without the rating.

Screenshot of a title in a widget with the ratings display
Screenshot of a title in a widget without the ratings display

Below is an example of a widget with all three display options enabled.

Screenshot of a title in a widget with the title, author, and rating display

Style to use when displaying the list widget

There are several options for widget display styles. Use the drop down menu to change the style of a list widget.  

  • Horizontal

  • Vertical

  • Single Title

  • Single Title with Next Button

  • Text Only List

Screenshot of the display style dropdown menu

Horizontal

Here is an example of a Horizontal widget.

Screenshot of a horizontal widget style

Vertical

Here is an example of a Vertical widget. 

The title and author do not display in this display style, even if enabled.

Screenshot of the vertical widget style

Single Title

The Single Title style will display only one title.

Here is an example of the Single Title style.

Screenshot of the single title style

There are no user controls in the Single Title style. If more than one title is being displayed, you should enable auto rotation so patrons can see all titles.  

Single Title with Next Button

The Single Title with a Next Button style will display only one title and includes user controls with the Next button.

Here is an example of the Single Title with a Next Button.  The user will have control to scroll through the items.

Screenshot of the single title with next button style

Here is an example of a library that is using multiple Single Title with a Next Button to display books, movies, music and games.

Screenshot of several single title with next button widgets on single webpage

Text Only List

The Text Only List style will display the information without images.

Here is an example of the Text Only List

Screenshot of the text only style

Auto Rotation option

Screenshot of the auto rotation option

The should the widget automatically rotate between titles option forces the the carousel to advance automatically. You can enable this option on the Horizontal, Vertical, and Single Title widgets. 

If this option is enabled, a Play/Pause button will display in the widget which will allow users to pause the auto-rotation to meet accessibility standards.

Screenshot of a horizontal widget with the auto rotation option, highlighting the play pause button

Cover Size

The cover size to use when showing a widget has a drop down choice of Small or Medium.

Screenshot of the cover size option

Here is an example of the Small cover size on a Horizontal widget.

Screenshot of widget with the small cover size option

Here is an example of the Medium cover size on a Horizontal widget.

Screenshot of widget with the medium cover size option

Custom CSS

The Custom CSS File is for styling the widget for your website. If you use this option in the widget, the corresponding CSS file for the widget should be hosted on your website. The URL to the hosted Custom CSS File is entered in the Custom CSS File field. 

Screenshot of the custom CSS file field

Marmot recommends that you add custom CSS for widgets on your Pika Admin page under Additional CSS.

Top of page


Display lists as

The Display lists as is a function that determines how you display multiple lists within one List Widget. There is a Tabbed Display or a Drop Down List.

Screenshot of the display lists as field

Here is an example of the Tabbed Display style. The Tabbed Display is the most common option

Screenshot of a horizontal widget with the tabbed display style

Here is an example of the Drop Down List style. The Drop Down List style allows users to choose the widget tab they wish to view from the drop down menu at the top of the widget.

Screenshot of a horizontal widget with the drop down list display style

Top of page

Lists

The Lists table controls the various tabs that are applied to a list widget.

The Name in the Lists table is the title of the given tab. The Source field is what Pika uses to reference the source list or search for the specific tab. You can drag and drop with the arrows in the Sort column to reorder the tabs. Use the Add New button to create a new tab in the existing widget.

Screenshot of the lists table highlighting the columns and add new button

Top of page

Live Preview

You can view the changes you’ve committed to the widget in real time with the Live Preview. There are two Live Preview windows in the form. The first, under the List Widget Integration Notes section is the preview for the most basic list widget. The second, under the List Widget with Resizing Integration Notes is the preview for the same widget with automatic resizing.

Basic preview

Screenshot of the basic live preview

Preview with resizing

Screenshot of the live preview with resizing

You can also use the Preview Widget as a Page option to preview your widget on a separate webpage, which will more accurately represent what the widget might look like on a webpage on your library website. Right click the button to open the preview webpage in a new tab.

Screenshot of the list widget admin page highlighting the preview widget as a page buttonScreenshot of the widget preview webpage

Creating a List Widget from User List or adding a User List as a List Widget tab

You can add to an existing list widget or create a new list widget from the admin controls in a public User List.

In the My Lists page in the Account, choose a public list that you would like to add to your List Widget.

Screenshot of a user list in the my lists page

If the Make Public button is showing, click it to make your list public. Otherwise, you will not see the Create Widget button.

Screenshot of the user list options highlighting the make public button

Public lists will have the necessary Admin Options.  Click on the drop-down menu and choose Create Widget.

Screenshot of the my lists options, highlighting the admin options menu and the create widget option

Use the Select a widget menu to select an existing widget if you want to add the list as a tab to an existing widget. If you want to create a new widget from the list, choose the Create a new widget option from the Select a widget menu. Add a relevant name in the New Widget Name / New Tab Name field and click Create widget to complete the action.

Screenshot of the create widget dialog highlighting the name field and the create widget button

Here is an example of a list that has been added to the List Widget.

Screenshot of a widget highlighting a newly added tab from the create widget option

Top of page

Creating a List Widget from Search Results

You can create a List Widget from Search results or use the search results that populate an existing Browse Category.

If you’re creating a list widget from unique search results, build the desired search to use as the source for your List Widget. If you’re creating a list widget from a browse category search, click on the title of the browse category next to the spyglass icon to access the search results that populate the browse category.

Screenshot of the catalog homepage highlighting the search access link for a chosen browse category

At the bottom of the page of the desired search results click on Create Widget (you must be logged in with your Pika admin account to see this option).

Screenshot of the search tools highlighting the create widget admin search tool

The Create a Widget dialog will popup.  Use the Select a widget menu to select an existing widget if you want to add the search as a tab to an existing widget. If you want to create a new widget from the list, choose the Create a new widget option from the Select a widget menu. Add a relevant name in the New Widget Name / New Tab Name field and click Create widget to complete the action.

Screenshot of the create widget dialog highlighting the select a widget menu, the name field, and the create widget button

Completing the action will direct you to the List Widget admin page for the new widget or the widget you added the search to as a tab, respectively.

Screenshot of the list widget admin page

Top of page

iFrame Embed Code

In the widget admin page, scroll down to the Integration notes.  You will see the iframe code.  If the widget is finished, you can copy the HTML code for the iframe and embed it into your library website.  The width and height may need to be changed to fit on your website. 

The basic iframe does not resize well for mobile devices.

Please be mindful of the accessibility requirements for the iframe, specifically providing an iframe title for the widget. There is linked documentation in the integration notes.

When inserting the widget title in the iframe code, remove the brackets from the code, leaving only the quotation marks around the title you’re providing e.g. title=”Embedded Widget Title”

Screenshot of the basic list widget integration code, highlighting the iframe and accessibility standards notes

Top of page

List Widget with Resizing Embed Code

Scroll down to the List Widget with Resizing and Integration notes.  Copy the entire code to use to embed into your website.  

This code will resize widgets on mobile devices.

Please be mindful of the accessibility requirements for the iframe, specifically providing an iframe title for the widget. There is linked documentation in the integration notes.

When inserting the widget title in the iframe code, remove the brackets from the code, leaving only the quotation marks around the title you’re providing e.g. title=”Embedded Widget Title”

Screenshot of the list widget with resizing integration code, highlighting the iframeScreenshot of the list widget with resizing integration code, highlighting the accessibility standards notes

Top of page

Adding multiple List Widgets to a website

You ​will not need all of the code for each widget.  Below is an example mark-up for multiple widgets, and the inclusion of the resizing code just once. 

You will need an additional Jquery line jQuery("#listWidget178").iFrameResize(); for each widget that is​ on the page.

<!-- Multiple Widgets placed throughout Page -->
<iframe id="listWidget178" onload="setWidgetSizing(this, 30)" src="http://opac.marmot.org/API/SearchAPI?method=getListWidget&id=178&resizeIframe=on" width="650" scrolling="no"></iframe> 

<!-- 2nd widget -->
<iframe id="listWidget179" onload="setWidgetSizing(this, 30)" src="http://opac.marmot.org/API/SearchAPI?method=getListWidget&id=179&resizeIframe=on" width="650" scrolling="no"></iframe> 

<!-- 3rd widget --> 
<iframe id="listWidget180" onload="setWidgetSizing(this, 30)" src="http://opac.marmot.org/API/SearchAPI?method=getListWidget&id=180&resizeIframe=on" width="650" scrolling="no"></iframe>

<!-- Add this code just once, adding a iFrameResize( ) line for each additional widget -->

 <!-- Horizontal Resizing : Based on Iframe Content -->

<script type="text/javascript" src="http://opac.marmot.org/js/iframeResizer/iframeResizer.min.js"></script>
<script type="text/javascript">
	jQuery("#listWidget178").iFrameResize();
	jQuery("#listWidget179").iFrameResize(); /* 2nd widget */
	jQuery("#listWidget180").iFrameResize(); /* 3rd widget */
</script>

<!-- Vertical Resizing : When Iframe is larger than viewport width,
	resize to 100% of browser width - 2 * padding (in px) -->

<script type="text/javascript">
	setWidgetSizing = function(iframe, OutsidePadding){
		originalWidth = jQuery(iframe).width();
		wasResized = false;
		jQuery(window).resize(function(){
			resizeWidgetWidth(iframe, OutsidePadding);
		}).resize();
	};

	resizeWidgetWidth = function(iframe, padding){
		if (padding == undefined) padding = 4;
		var viewPortWidth = jQuery(window).width(),
			newWidth = viewPortWidth - 2*padding,
			width = jQuery(iframe).width();
		if (width > newWidth) {
			wasResized = true;
			return jQuery(iframe).width(newWidth);
		}
		if (wasResized && originalWidth + 2*padding < viewPortWidth){
			wasResized = false;
			return jQuery(iframe).width(originalWidth);
		}
	};

</script>

Top of page

Related Documentation

  • No labels