Library:Circle/Advanced Techniques for cIRcle Feeds
Print me |
|---|
| Print this page |
Summary
cIRcle, Feeds, and Shortcodes
This article assumes that you're familiar with cIRcle and some of the basic shortcodes developed for UBC's CMS WordPress platform. If any of those terms are confusing, you might want to start here. That guide describes the creation and use of customized ATOM feeds of cIRcle content, including embedding feeds in a CMS WordPress site.
Visit our website for more information about cIRcle.
The focus of this guide
You're already familiar with creating customized feeds of cIRcle content, as well as embedding those feeds into a CMS WordPress page or site, using shortcodes and widgets. In this guide, you'll learn techniques to efficiently create more complicated displays of information from cIRcle feeds, by using shortcodes and by modifying a feed's URL. You will also learn to use the [tab] shortcode to create tabbed displays of feeds or other content.
Why are these techniques necessary?
The basic process of creating and displaying customized feeds works well for creating and displaying short feeds. And it is straightforward enough for creating and displaying small numbers of feeds. These feeds are ideal for displaying the most recent publications, theses/dissertations, or other items produced by a faculty or department. However, if you want to create complex displays of feed information, very large feeds, or large numbers of similar feeds, the basic customized feed process is often insufficient, inefficient, or both. The techniques discussed here offer solutions and work-arounds to these problems, allowing users to create complex or lengthy displays of information from cIRcle.
The basic process cannot generate feeds displaying more than 100 items. It can also be unnecessarily repetitive, if you wish to create many similar feeds. In addition, the dates displayed by cIRcle can be misleading, especially for theses and dissertations produced prior to 2008, which were retroactively added to the repository.
|
Note: cIRcle contains over 30,000 theses and dissertations originally produced between 1919 and 2007, which were digitized and uploaded subsequent to 2008. Unfortunately, when these items appear in a feed, the date displayed is the "Submit Date"--i.e., the date the thesis was uploaded, rather than a copyright date. Feeds are sorted based on the same "Submit Date". Thus, a 1970 thesis uploaded in 2010 will display a 2010 date, and will appear chronologically after a 1995 thesis which was uploaded in 2008. As a result, feeds which display many items--e.g., a feed showing all of the theses/dissertations produced by a department--will not display in order of copyright, nor will the feed items display a meaningful date. Present and future cIRcle submissions, as well as non-thesis materials, are not affected by this problem. This is an issue with the cIRcle database software, and one that cIRcle staff are currently working to resolve. However, until that happens, both the date displayed on cIRcle items and the "Sort By Submit Date" option in Advanced Search may produce misleading results for pre-2008 theses and dissertations. |
Creating and Displaying Large Feeds
Default settings in both cIRcle and WordPress limit the number of items that can be displayed in a single feed. These instructions provide a way around those limits, allowing the creation of very long feeds. These long feeds can be used to display all of the items in a given community or collection, e.g. a list of all Forestry Theses or all publications from the B.C. Mine Reclamation Symposia.
Creating Unlimited Feeds via cIRcle
Advanced Searches in cIRcle have the option to show between 5 and 100 results per page. An ATOM feed generated from an Advanced Search is, by default, set to display the same number of results. This prevents the creation of feeds with more than 100 results. Fortunately, creating such a feed is only slightly more complicated than creating a standard-length feed.
First, create your custom search from the Advanced Search screen. Select the option to see 10 Results/page (any number works, but this example uses 10).
Second, generate an ATOM feed from that search, as normal. (Remember, just scroll down to the bottom of the page and click the ATOM link.)
Third, take a look at the URL for that feed. One section of the URL will read rpp=10. Delete the "10" and replace it with an arbitrarily large number--say, "9999".
Fourth, reload the feed, using the newly-revised URL. The simplest way to do this is to simply press enter after you have replaced the "10" with "9999".
This will result in a new feed, with a revised maximum number of results shown per page: 9999. In practice, the feed will show every result from your search, unless, of course, your search returns more than 10,000 items. (In that case, you should either enter a number larger than 9999 or change your search parameters---10,000 results would lead to a really, really long list.)
This feed can then be used as would any other customized cIRcle feed.
|
IMPORTANT! If you do not reload the feed using the modified URL, it will not work when embedded in a website. Simply revising, copying, and pasting the URL is not enough. You need to revise, reload, copy, and paste. |
Shortcode Display in CMS WordPress
On UBC CMS WordPress sites, feeds displayed using shortcode are limited, by default, to 15 items. To display a feed with more items--for example, a feed of all theses and dissertations from a single department--the [feed] shortcode must include the parameter num=X. Here, X can be another arbitrarily large number, such as 9999. To include this parameter in a feed shortcode, simply add "num=9999" to a piece of shortcode. This will ensure that every item in the feed will be displayed (unless the feed has 10,000 or more items, in which case you may wish to choose a larger number or reevaluate the purpose of the feed).
Displaying All Items in a Collection
One of the most interesting opportunities made possible with cIRcle feeds is the display of all theses and dissertations produced by a Department or Faculty. Many UBC Departments and Faculties already provide a list of past theses and dissertations on their websites, without using feeds from cIRcle. However, manually creating such lists is time consuming, and can be incomplete.
Using cIRcle feeds for this purpose allows easier creation and automatic maintenance/update of such lists, greatly reducing the effort required on the part of Department/Faculty staff. Feed-based lists also provide easy access to the actual theses and dissertations, which are available as pdf files in cIRcle.
All Item Feeds
The preceding section provides instructions for creating very long feeds and displaying them on WordPress. This allows the creation of feeds which include every thesis or dissertation produced in a particular Faculty or Department. However, such a feed will currently display misleading dates, and be arranged in an order that does not reflect the items' actual copyright date. If dates are not essential, however, the long feed is a very easy way to create a complete feed.
Single Year Feeds Based on Copyright Date
You can avoid this problem by creating multiple feeds based on the copyright date of theses and dissertations. Each feed can be limited to items produced in a single year, and individual feeds can be arranged chronologically on a webpage. Creating this sort of feed is very simple: just conduct a custom search which includes "Thesis Copyright Date" as a search type.
The resulting feed can be added to CMS WordPress shortcode, to create a list of all theses/dissertations from a single year.
Efficiently Creating Multiple Short Feeds
The above method is adequate on the small scale, but quickly becomes tedious if you are creating dozens of individual feeds. For example, if you wish to display all theses/dissertations produced by the Anthropology Department, from 1950 onwards, you could generate the feed URLs by individually creating a custom search for each year, then creating the ATOM feed, then copying the URL, then repeating the process for the next year.
Thankfully, there's a faster way. As with creating very long feeds, this technique involves generating a feed, then altering the URL.
First, generate your initial single-copyright-year feed, as above.
Second, in the URL for that feed, identify the copyright date information. In the following URL, this is the section in bold.
https://circle.ubc.ca/open-search/?query=%28%28program%3AAnthropology%29+AND+%28copyrightdate%3A1984%29%29&start=0&rpp=100&sort_by=3&order=DESC&format=atom&scope=2429/2
Third, to create a new feed for a different copyright year, simply edit this date:
. . . 28copyrightdate%3A2010%29%29&start=0&rpp=100 . . . etc
Fourth, you can use the newly-revised URL as a part of shortcode, or embed it in any other webpage that supports an ATOM feed.
Fifth, in CMS WordPress, you can save even more time by copying and modifying entire sections of shortcode. Once you have created a single block of shortcode, including one single-year-feed URL, you can copy+paste+revise that block, to create multiple new displays of ATOM feeds, arranged chronologically by year.
(Note: For demonstration purposes, each feed in this example was limited to 3 items displayed. More than 3 Mechanical Engineering theses/dissertations are produced yearly.)
Tabs
Another interesting way to display cIRcle feeds is through tabbed displays. This allows multiple feeds or other information to be displayed in the same area of a page, keeping pages short, clean, and easy to navigate.
The [tab] shortcode is the key to these displays. For example, the first entry (2012) on this page, which separates theses into MA and PhD work, is produced by the following shortcode:
[tabs]
[tab title="MA"]
[feed url="https://circle.ubc.ca/open-search/?query=%28%28program%3AAnthropology%29+AND+%28copyrightdate%3A2012%29+AND+%28%22Master+of+Arts%22%29%29&start=0&rpp=100&sort_by=3&order=DESC&format=atom&scope=2429/2" num=1000 view=rsswidget show_author=true]
[/tab]
[tab title="PhD"]
[feed url="https://circle.ubc.ca/open-search/?query=%28%28program%3AAnthropology%29+AND+%28copyrightdate%3A2012%29+AND+%28%22Doctor+of+Philosophy%22%29%29&start=0&rpp=100&sort_by=3&order=DESC&format=atom&scope=2429/2" num=1000 view=rsswidget show_author=true]
[/tab]
[tab title="Notes"]
Note: You could add a note here if you wanted. Or other text, including other shortcodes. You could even embed wiki content in a tab like this.
[/tab]
[/tabs]
The [tab] shortcode is very versatile, accepting feeds, wiki embedding, text, and other information in the tabs. The [tab] shortcode can even be added into widget areas via the Section Widget.