Library:Circle/Creating and Using Atom Feeds From cIRcle Content
Print me |
|---|
| Print this page
|
|
This article is still being drafted. This means that the article is still being worked on and information may be incomplete. This template will be removed when the article is finished. If you have any concerns, please start a discussion on the talk page. |
Summary
This page is a guide to creating and using web syndication feeds derived from content in cIRcle, UBC's digital repository. ATOM feeds from cIRcle enable UBC departments to display selected content from cIRcle on their own web pages.
This guide is intended for UBC Library staff or administrators of UBC faculty and department websites.
What is UBC cIRcle?
cIRcle is UBC's digital repository, an open access, online repository designed to showcase and preserve UBC's scholarly output. All UBC theses and dissertations are publicly available through cIRcle, as are many articles, conference papers, data sets, and other multimedia materials.
Visit our website for more information about cIRcle. You may also wish to review our FAQs.
Why use Atom feeds from cIRcle?
Atom feeds are web syndication tools which enable websites to display content from other sites. Using Atom feeds from cIRcle, UBC department or faculty websites can display lists of theses and dissertations produced by their students--these could be lists of the most recent theses produced, of theses from a single degree or year, or even of all theses ever produced by students from that department. These feeds feature direct links to cIRcle pages where any user has open access to .pdf copies of each thesis.
In addition to providing open access to student research, feeds allow departments to publicize or celebrate student achievements. Feeds could also present prospective students with examples of the type, quality, and subjects of scholarship produced by previous students.
Finally, feeds save effort. Instead of website administrators manually creating and updating a list of theses or dissertations, a feed will update automatically, whenever new material is submitted to cIRcle. As students must submit their thesis or dissertation to cIRcle in order to graduate (with some exceptions), the cIRcle feed will be comprehensive.
What's in this guide?
This guide teaches you to create several basic types of customized Atom feed, using the Advanced Search feature in cIRcle. You will also learn how to manipulate feed URLs to make unusually long or numerous feeds. The final section of the guide provides some useful techniques for adding cIRcle feeds to websites based on UBC's Content Management System (CMS), which uses a WordPress platform.
back to top
Custom Feed Basics
Start at the cIRcle Advanced Search screen.
Create a Custom Feed For Recent Theses
The following steps generate a custom Atom feed, featuring the most recent Forestry theses and dissertations, using cIRcle's Advanced Search feature.
- In the "Search Scope" field, select "Graduate Theses and Dissertations."
- In the "Search Type" field, select "Thesis Program" and enter the name of the program (eg. Forestry).
- To retrieve the items which have been most recently submitted to cIRcle, select “Submit Date” from the “Sort items by” list.
- Set the number of results you wish to retrieve per page. (Note: the number of results per page is, normally, the maximum number of items which can be displayed in the ensuing feed. Very large feeds are discussed later.)
- Click "Go" to conduct the search.
- At the bottom of the search results page, click the Atom link. This will generate a web feed drawn from these search results, arranged according to the settings you selected.
- Use! To use this feed on a website, you will need the URL. Simply select and copy, then go put it to work!
Note: depending on your browser settings, the feed page might display different. Don't worry--the URL will still work.
Limiting a Feed by Degree
The Search Type "Thesis Degree" allows you to further refine your search results and feed to theses produced in a specific degree program. Simply set the second Search Type field to "Thesis Degree," and type in the desired degree.
You can turn these search results into a feed by clicking the Atom link, as normal.
|
IMPORTANT! This option is not yet available through Advanced Search. However, cIRcle is working on it, and the feature should be implemented and available soon. |
Limiting a Feed to a Single Year
The process of creating a feed with results from a single year is equally straightforward.
From the Advanced Search page, select the Thesis Program as normal, and select "Thesis Copyright Date" as the Search Type. Then enter the desired year in the search feed and generate a feed as normal. The result will be an unsorted list[1] of theses and dissertations which were copyrighted in the selected year.
Note: only theses and dissertations have a copyright date in cIRcle.
back to top
Creating a Feed For a Range of Dates
Perhaps you want a feed with all items produced from 2010 to 2012, from the 1980s, or between 1975 and 2000. This date range search is almost identical to the Single Year search; all that differs is what you type into the search field.
Instead of entering a single year, you can:
- Enter multiple years, e.g.: 2010 2011 2012
- Use a wildcard (*) to retrieve results from a decade, e.g.: 198*
- Combine these two methods, e.g.: 1975 1976 1978 1979 198* 199* 2000
These searches result in an unsorted list of all items that meet the Copyright Date criteria specified.
|
IMPORTANT! Ensure that you do not use hyphens or dashes when searching for theses from specific years. Searches for Copyright Date 1975-2000 or Copyright Date 1975 - 2000 will not return any results. |
Advanced Techniques for Custom Atom Feeds
This section provides instructions in two related techniques which are useful for efficiently displaying a large number of cIRcle links on a single webpage. A third option allows you to create feeds which combine more than 3 different thesis programs. All three of these techniques require manual alteration of feed URLs.
A fourth technique lets you create non-secure feeds instead of the normal, secure (https:// ) custom feeds.
Generating Unlimited Feeds
Advanced Searches in cIRcle have the option to show between 5 and 100 results per page. A custom 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, indicating that this feed shows 10 Results Per Page. 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. This feed can then be used as would any other customized cIRcle feed.
In practice, the feed will show every result from your search--unless, of course, your search returns more than 10,000 items. If that happens, either use a larger number than 9999, or narrow your search.
|
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. |
Efficiently Creating Annual Feeds
The preceding instructions allow you to create a comprehensive list of theses and dissertations produced by a specific faculty or department. That process is simple, but the result is not very flexible. These very large feeds can be hard to read or use, and do not always display accurate date information.
To avoid these problems, and to make your comprehensive list more flexible, readable, and useful, you can create separate feeds for items from every year. Above, you learned how to generate a feed of items from a single year. Manually generating dozens of feeds this way, however, would be very tedious and time-consuming. Fortunately, there's a shortcut!
- First, generate a single-year feed. Copy the URL, and embed it in the desired webpage. If you aren't ready to use it just yet, you should paste it into a text file.
- Second, examine your URL and identify the year digits (in bold below)
- Third, change the year digits to another year.
- Fourth, copy, save, and/or use this URL on your website.
- Fifth, repeat! Every time you modify the year digits, the URL will generate a feed with the new year's results. This allows you to create a comprehensive list of items, sorted by copyright year, without carrying out a new search for each year.
|
Tip! |
Feeds for Multiple Programs
The 3 search boxes in Advanced Search can be used to create feeds which combine items from up to three thesis programs, using the OR conjunction. For example, a feed might display the most recent History, Political Science, and Anthropology theses and dissertations.
To combine more than 3 programs in a single feed, it is necessary to alter the URL of a custom feed. By editing the URL, you can create a new feed that gets around the limitations of the Advanced Search screen.
1. Create a custom search for the program of your choice. Create a feed based on these search results using the ATOM link as normal.
2. In the feed URL, you will find a section which specifies the Thesis Program you’re searching for. The URL may look different depending on your browser. If you searched for Thesis Program: History, this section would either look like: ?query=%28%28program%3AHistory%29%29 or ?query=((program:History))
3. To add another program—e.g., Political Science—you just need to duplicate the program section, by adding (program:“Political Science”). This parenthetical phrase should be inserted after the first search term, between the first and second close parentheses. For example: ?query=((program:History) (program:“Political Science”))
- a. If your URL uses %28 and %29 instead of ( and ), insert the new program query between the first and second %29, like so:
- ?query=%28%28program%3AHistory%29(program:“Political Science”)%29
- b. The browser will understand your added punctuation, even if the other parentheses are replaced with %28 and %29 in the URL.
- c. If you are copying and pasting the program queries, make sure they were written in a simple text editor. The formatting of Microsoft Word text may cause problems when pasted into a URL.
4. Once you have a new, revised URL, you can use it wherever a feed URL is needed.
back to top
Feeds Without HTTPS
By default, all of cIRcle's feeds are secure, using a URL which begins with "https://". Some web platforms, such as the basic free version of WordPress, cannot handle these secure feeds very well.
Fortunately, the URL holds an easy solution. Once you've generated your feed, simply change the "https://" in the URL to "http://". Reload the feed, using the new URL. The result is a non-secure version of the custom feed, usable anywhere.
Adding Feeds to UBC CMS Websites
UBC's Content Management System is a customized WordPress platform for hosting and creating webpages. The basic elements of WordPress have been enhanced with useful tools and techniques, for easy and convenient content creation. This section discusses how some of those tools can be optimized to work well with feeds of cIRcle content.
Basic Embedding With Shortcodes
Adding a cIRcle feed to a CMS WordPress page is extremely easy, thanks to the magic of shortcodes. Shortcodes are snippets of customized code designed for CMS pages, which allow you to “do nifty things with very little effort.”
In this case, the nifty thing is adding a custom Atom feed to your page with the [feed] shortcode, rather than using the RSS Widget. Shortcode can be added to any text area on a WordPress site.
|
What about the RSS Widget? CMS websites, and many other Wordpress sites, include a widget expressly designed for RSS feeds. This is a very simple tool to use, but it is not very flexible. When you use the RSS Widget, this creates a feed in a Widget Area. However, this feed will be visible on every page of your website--and only in the specified Widget Area. The RSS Widget also lacks the display options of the shortcode method. Basically, RSS or Atom feeds from shortcode are more flexible, more customizable, and more useful than feeds from the RSS Widget. |
Using the Feed Shortcode
To embed a feed using shortcode, simply add this text to a Wordpress page, using the URL from that feed: [feed url="INSERT URL HERE"]
The result looks like this:
Feed Shortcode Parameters
The feed shortcode has a number of parameters--options which can be used to alter a feed’s appearance. The full list is here, but the most useful are:
- url=”URL” This is the only essential parameter.
- num=X The feed will display only the first X items(e.g. 5, 10, 25).
- view=rsswidget Displays the feed in RSS style bullet points. This view allows the date and author parameters to display correctly.
- show_author=true Displays the author(s) of each item. Only functions in rsswidget view.
- show_date=true Displays the submission date of each item. Only functions in rsswidget view. Be aware that this is not the copyright date.
- view=blog Displays the title and abstract of the item. Note: you cannot have two view parameters in the same feed.
- excerpt_length=X When using view=blog, this parameter limits the abstract to X characters. It does not limit the length of the title, author, or date displays.
Parameters are added into the [feed] brackets, as seen here:
The resulting CMS webpage looks like this:
Long Feeds and Shortcodes
On CMS WordPress sites, feed displays created with shortcode are limited, by default, to 15 items, even if the feed itself is naturally very long.
To display a feed with more items, the [feed] shortcode must include the parameter num=X. Here, X can be any 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, but that's probably too long for any feed).
Multiple Feeds and Shortcodes
If you have created multiple short feeds, these can be added to a CMS webpage with ease. All you need to do is add the proper URL into the shortcode. For maximum efficiency, you can place your original URL into a block of shortcode, with all the desired parameters. Then just copy and paste that shortcode, and alter the URL in each segment.
In the example below, the initial shortcode is outlined in blue. Red arrows mark the only part of the entire block of shortcode which needs to be changed. As you can see here, this simple change results in two separate feeds, one from 1984, and one from 2004.
You may wish to have a bold heading before each year's feed with the year number/degree type, or some other visual cue separating the feeds. This will help users scroll quickly through your web page to find feeds of interest.
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 the page shown above, 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.
back to top
Feeds, Shortcodes, and Widgets
To display cIRcle feeds in different parts of your CMS webpage, you can combine shortcodes with widgets. With the [feed] shortcode, you can add a feed into the text box of any widget, in any widget area.
This is most useful with the Section and Section (Tabbed) widgets in WordPress. These widgets create a unit of text (or tabbed units of text) which can be displayed on all of your pages, certain categories of page, or on individual pages.
References
If you have questions or would like more information, contact the UBC cIRcle Office.
- ↑ Currently, cIRcle is not capable of sorting results by copyright date. Theses and dissertations written prior to 2008 were digitized and uploaded to cIRcle as part of the Retrospective Thesis project, during 2008-2012. As a result, these items all have a Submit Date between 2008 and 2012, which does not reflect their actual dates of creation.