4. Web Integration API
An important requirement of SWITCHcollection is the possibility of it's integration into an existing infrastructure. The Web Integration API offers very simple ways of integration without requiring any programming. It consists of two parts:
- Basic link embedding: this is just the common way to link or refer to sections, functions and objects on the SWITCHcollection website.
- The Upload Web Form (loroform) allows to put new data objects in the community repository. It provides a straightforward way to upload content and metadata from an external web application to the community repository with a single http-post request.
- The Web Page Embedding (lorem) is a simple way to add SWITCHcollection browse and search capabilities into any website - just by putting a one-line javascript code snippet in a web page.
4.1 Basic Linking
It is possible to link to sections and objects on the SWITCHcollection site as you usually expect. Just navigate to the respective page and use the http address in the browser's address bar. Examples:
- Link to an Object: https://collection.switch.ch/objects/LOR:1731/
- Link to a Folder: https://collection.switch.ch/collections/LOR:3
SWITCHcollection also allows to use the search function and dynamically execute search requests:
- Link to the results of the search term kolloquium: https://collection.switch.ch/results?q=kolloquium
- Include a search field in a website. Example:
Source code for the above search field:<form method="get" action="https://collection.switch.ch/results"> <input type="text" size="30" name="q" value="" /> <input type="submit" value="search" /> </form>
4.2. Upload Web Form (loroform)
If a user exports a learning object using an export adapter as described in chapter LMS Integration he/she is redirected to a web-based form where the metadata values of the object are to be interactively confirmed and refined. In order to relieve the user as much as possible, the web-based form should be initialized with a maximum of already available metadata information.
Requirements: The web form requires Shibboleth authentication (SWITCHaai) and the user has to have permissions to edit somewhere in the community repository.
SWITCHcollection Upload Form
The upload form is a manual Step to confirm the Export from a Learning Management System (LMS) or any other website outside the SWITCHcollection.
Process
Do a POST request to https://collection.switch.ch/loroform. See the List below, what the Names of the POST Variables need to be that the Form is correctly filled.
Fields
| POST Variable Name | loroform Element Title | Element in Specification | Accepted Values |
| title | Title | title | Free Text |
| collection | Is Part of Collection | rel:isMemberOfCollection | any Collection PID (eg. LOR:3) |
| source | Source ID | source | Free Text (if any object with the same source allready exists in the Collection then the object will be replaced.) |
| aaiid | SWITCHaai | aaiid | set by Form automatic |
| creator | Creator | creator | Free Text |
| accessRightsAttr | Access Rights | accessRights | "private", "group","institution", "federation","public" |
| accessRights | (none – Access Rights addition) | accessRights | Group Name of an existing Group |
| rightsAttr | Rights | rights | "private", "group", "institution", "federation" |
| rights | (none – Rights addition) | rights | Group Name of an existing Group |
| license | License | license | http://collection.switch.ch/spec/2008/licenses/ Values from the ID column |
| thumbnail[contenturi] | Source URI | contenturi | any valid URL |
| thumbnail[format] | Mime type | format | http://collection.switch.ch/spec/2008/mimetypes/ Values from the "ID" Column |
| thumbnail[formaturi] | Detailed type | formaturi | http://collection.switch.ch/spec/2008/format/ Values from the "Format" Column (List can be expanded if needed) |
| datastreams[n][contenturi] | Source URI | contenturi | any valid URL. Datastream is always managed content "M" |
| datastreams[n][format] | Mime type | format | http://collection.switch.ch/spec/2008/mimetypes/ Values from the "ID" Column |
| datastreams[n][formaturi] | Detailed type | formaturi | http://collection.switch.ch/spec/2008/format/ Values from the "Format" Column (List can be expanded if needed) |
| contributor[n] | Contributor | contributor | Free Text |
| publisher[n] | Publisher | publisher | Free Text |
| rightsHolder | Rights holder | rightsHolder | Free Text |
| alternative[n] | Alternative | alternative | Free Text |
| tableOfContents | Table of contents | tableOfContents | Free Text |
| abstract | Abstract | abstract | Free Text |
| subject[n] | Subject | subject | Free Text |
| discipline[n] | Discipline | subject | http://collection.switch.ch/spec/2008/disciplines/ Values from the "ID" Column |
| description[n] | Description | description | Free Text |
| issued | Issued | issued | Date as YYYY-MM-DD |
| language[n] | Language | language | http://collection.switch.ch/spec/2008/languages/ Values from the "ID" Column |
| educationLevel[n] | Education level | educationLevel | Free Text |
| instructionalMethod[n] | Instructional method | instructionalMethod | Free Text |
| type | Type | type | http://collection.switch.ch/spec/2008/types/ Values from the "DCMI Type" Column |
| extent[n] | Size/Duration | extent | Free Text |
| backlink | --- | --- | an URL that is shown below the Form. It should bring you back, where you come from. |
| backlinktext | --- | --- | The text of the backlink. 'Back' is default if none given. |
Example Form
This is an example Form which creates a Post Request to test.collection.switch.ch and then fills up the LORoForm with the given Values.
<html><head><title>Example</title><head><body>
<form method='POST' action='https://test.collection.switch.ch/detour/index.php'>
<input type='hidden' name='title' value='The Title of the Object'>
<input type='hidden' name='collection' value='LORtest:4'>
<input type='hidden' name='source' value='myID12205299571'>
<input type='hidden' name='creator' value='Renato'>
<input type='hidden' name='accessRightsAttr' value='private'>
<input type='hidden' name='accessRights' value=''>
<input type='hidden' name='rightsAttr' value='institution'>
<input type='hidden' name='rights' value='uzh.ch'>
<input type='hidden' name='license' value='http://creativecommons.org/licenses/by-nc/2.5/ch/'>
<input type='hidden' name='thumbnail[contenturi]' value='http://www.zisch.ch/openmedia_custom/files/BXMediaOne195656file.jpg'>
<input type='hidden' name='thumbnail[format]' value='image/jpeg'>
<input type='hidden' name='thumbnail[formaturi]' value='ims-qti'>
<input type='hidden' name='datastreams[0][contenturi]' value='http://www.auf-die-berge.de/wallis74grosz.JPG'>
<input type='hidden' name='datastreams[0][format]' value='image/gif'>
<input type='hidden' name='datastreams[0][formaturi]' value='scorm'>
<input type='hidden' name='datastreams[1][contenturi]' value='http://lh5.ggpht.com/_hYbvMZefhOs/R6oB7-2LwcI/AAAAAAAACAg/3oHjylUpgPY/P2054718.jpg'>
<input type='hidden' name='datastreams[1][format]' value='application/gzip'>
<input type='hidden' name='datastreams[1][formaturi]' value=''>
<input type='hidden' name='contributor[0]' value='SWITCH'>
<input type='hidden' name='contributor[1]' value='Example'>
<input type='hidden' name='publisher[0]' value='PublisherA'>
<input type='hidden' name='publisher[1]' value='PublisherB'>
<input type='hidden' name='publisher[2]' value='PublisherC'>
<input type='hidden' name='rightsHolder' value='SWITCH'>
<input type='hidden' name='alternative[0]' value='eine Alternative'>
<input type='hidden' name='alternative[1]' value='eine andere Alternative'>
<input type='hidden' name='tableOfContents' value='1. Einführung, 2.Schlusswort'>
<input type='hidden' name='abstract' value='Dies ist nur ein Beispiel. Nichts ist wirklich echt.'>
<input type='hidden' name='subject[0]' value='Gletscher'>
<input type='hidden' name='discipline[0]' value='6302'>
<input type='hidden' name='description[0]' value='Ein paar Bilder'>
<input type='hidden' name='bibliographicCitation' value='Bibl. Referenz'>
<input type='hidden' name='issued' value='2006-03-20'>
<input type='hidden' name='language[0]' value='eng'>
<input type='hidden' name='language[1]' value='deu'>
<input type='hidden' name='educationLevel[0]' value='Anfänger'>
<input type='hidden' name='educationLevel[1]' value='Fortgeschrittene'>
<input type='hidden' name='instructionalMethod[0]' value='Bilder'>
<input type='hidden' name='type' value='InteractiveResource'>
<input type='hidden' name='extent[0]' value='20 MB'>
<input type='hidden' name='extent[1]' value='2 Stunden'>
<input type='submit' value='POST Request (LORtest)' name='submit'>
</form>
</body></html>
4.3. Web page embedding (lorem)
The purpose of content embedding is to allow to embed search functions, contents and search results in remote web sites or web applications. A user can perform most search and query actions in SWITCHcollection without having to leave the remote web site. Embedded search results come in the default SWITCHcollection style but can be changed by a customized CSS or even own html templates.
The content embedding function differs from the REST API in the following aspects:
- it allows to easily embed contents and search results of SWITCHcollection in any web page.
- it focuses on searching, downloading and displaying of objects (rather than getting, creating or modifying them)
- it is exposed to the public
-
it is not RESTful. It's results are human readable HTML pages
Any Site or even Part of SWITCHcollection can be embedded in an external Site. Therefore the Site Administrator of the remote Site needs to include the following line in its HTML code:
<script type="text/javascript" src="https://collection.switch.ch/lorem.js?startURL=https://collection.switch.ch/disciplines/4761"> </script>
Parameters
| Parameter | Req | Description | Default |
| startURL | optional | Any valid URL from SWITCHcollection which needs no authentication. | https://collection.switch.ch |
| css | optional | An URL to a css file (including http://) or 'none' if no css is needed. In that case you should make sure that the html and classes are adressed in the main css file. | <empty> |
Customization of Look and Feel
The embedded html code that is generated by the javascript snippet should mostly inherit the style (font, size, colors, ...) from the web page that surrounds it. If this is not sufficient, a custom css stylesheet can be developped and added (parameter css). And finally, there is also the possibility to use custom templates, which offers most creative freedom. If you'd like to use your own templates, please contact us.
Limitations of Web Page Embedding
Web page embedding works fine with most static web sites, and also on sites with dynamically generated pages (i.e. using php or other web application server technology). The approach chosen for web page embedding does have a few limitations though.
Web page embedding does not work on web sites with strongly rewitten URLs, in particular if GET parameters are modified. Some CMS do heavily rewrite URLs.
Clicking on a link in the embedded part of SWITCHcollection causes a page reload which again make the browser to scroll to the top of the page. This may be a bit counter intuitive if a user has scrolled down to navigate through SWITCHcollection. This issue can be addressed by putting the embedded part on the top of a web page.